DropPay API - Bank v.1 - Pull¶

DropPay offers an API to enable your application to debit an other user account owner.

With Pull API your application can ask to another DropPay account owner to authorize

single or multiple debit transactions
debit transactions of fixed amount, limited to a maximum value, or opened to be defined by the puller
debit transactions recurringly executed by DropPay automatically.

An User can revoke a Pull authorization at any time.

Warning

Your application must act on behalf of the DropPay account owner who is the recipient party of the Pull you want to perform. Read Connection API reference first!

Submitting a Pull¶

A Pull is a RESTful entity. It is created with a POST and it persists on DropPay server side. When submitting the Pull the pulled account owner will receive a push notification on his DropPay mobile app with the summary of your request which will persist in the app until user decides to approve or reject it.

You may not know the username or the account IBAN you want to pull money from. If that's the case the sharing attribute of Pull response contains an Universal Link. This link can be rendered as QR code, or can be sent to Account Owner using your preferred sharing channel.

User then will import the sharing link into his DropPay mobile app to confirm it within the two-factor disposition flow.

Pull entity must be put in READY status if you want user is able to confirm it. You can create a Pull already in READY status (setting it explicitly in the POST payload) or you can work it in DRAFT status until you want, PATCHing it to READY only at the right time.

Pull entity does not represent the money transfer operation but its control resource. Actual money transfer is kept by Transfer REST entity.

A Pull can allow to execute a single Transfer or a list of Transfers.

Pull enables your application to transfer money only between two DropPay Accounts.

Currency is Euro (€).

Let's consider the json below

{
    "description" : "Mario's birthday gift",
    "transfer_amount": "30.00",
    "transfer_amount_policy": "FIXED",
    "policy" : "TRANSFERRED",
    "source": {
        "account": "IT48D3606400001098765432111",
    },
    "status": "READY",

}

Here, to collect money for Mario's birthday gift, a single, not repeatable, request of 30,00 € is submitted to IT63B3606400003471234567 account owner. Only one transfer will be performed before the Pull is set to DONE.

transfer_amount_policy is FIXED the money transfer will match exactly that amount and policy is TRANSFERRED to inform DropPay that money transfer must be performed simultaneously with payer approval.

See the REST Entity reference below for full details.

Pull enabling multiple transfers¶

The following Pull request enables you to transfer up to 200,00 € (LIMITED amount policy) for as many times as you want until 2019-03-31.

As long as the policy is TRANSFERABLE DropPay won't debit user at approval time, but you will need to perform transfers once the PUll has been approved.

{
    "description" : "Service Fee debit agreement",
    "transfer_amount" : 200.00,
    "transfer_amount_policy" : "LIMITED",
    "date_end" : "2019-03-31",
    "policy" : "TRANSFERABLE",
    "source" : {
        "account" : "IT48D3606400001098765432111",
    },
    "status": "READY",

}

See the REST Entity reference below for full details.

Pull with multiple recurring transfers¶

You may need to submit a payment plan, possibly due to the instalment payment you should receive.

DropPay lets you configure a Pull with recurring trnasfers.

Recurring transfers are executed automatically by DropPay starting at approval time and you won't need to perform any transfer.

{
    "description" : "Bike purchase instalment payment"
    "transfer_amount": 200.00,
    "transfer_amount_policy": "FIXED",
    "transfer_count": 60,
    "policy" : "TRANSFERRED"
    "source": {
        "account": "IT48D3606400001098765432111",
    },
    "recurrence" : {
        "period": `P2M`,
    }

}

period is a string ISO-8061 duration representation compliant. In the example above P2M define a 2-months period.

See the REST Entity reference below for full details.

Transfer Amount Policies

Here is a summary of the amount policies you can attach to the PUll:

FIXED : every transfer must have the same amount value of transfer_amount;
LIMITED : every transfer must have an amount value up to the transfer_amount's one;
OPEN : you can perform a transfer of any value without cap;

Performing Pull transfers¶

Once the Pull request has been approved by source account owner and its status is set to SCHEDULED by DropPay, you might need to perform transfer to pull money into your account.

This happens only if policy is TRASFERABLE and recurrence is unset.

Posting onto the Pull request a new transfer with the following JSON payload, transfer_amount_policy will be matched against your request and the request will result in the amount of money being trasferred from source party's account to recipient one.

    {
        "description" : "Mario's birthday gift",
        "amount": 30.00,
    }

See the REST Entity reference below for full details.

REST Entities¶

Every REST entity is described listing her properties with the following formatting conventions:

this is a property name
this is an example of property value
(type, policy, direction) is the specification of a property
- type can be "string", "number", "object" or a proper object class name
- policy can be "optional" or "required"
- direction can be "posted" or "received" depending on whether you set it in the request or you got it from the response
after the dash "-" there's the property description

name: example_value (type, policy, direction) - Property description

Pull¶

Pull

id: MRE1234568UN8 (string, returned) - Unique ID of the Pull Order
description: my label (string, optional posted) - description of the Pull for your convenience
transfer_description: my label (string, optional, posted) - description of the single transfer (if recurrence is set all transfers will have the same decription)
transfer_amount: 50.00 (number, required, posted) - requested amount of money, ignored if transfer_amount_policy is OPEN
transfer_amount_policy (enum, required, posted) - policy that determines how DropPay will evaluate the single transfer amount
- enum members
  - LIMITED - every transfer must have the same amount value of transfer_amount
  - FIXED - every transfer must have an amount value up to the transfer_amount's one
  - OPEN - you can perform a transfer of any value without cap
fee: 0.99 (number, optional, returned) - commercial cost of a single Trasfer run by this Pull, if not free
date_creation: 2016-07-16T19:20:30+01:00- Date the Pull request has been created
date_last_modified: 2016-07-16T19:20:30+01:00- Last date the Pull request has been modified
date_scheduled: 2016-07-16T19:20:30+01:00- Date of the planned future Transfer
transfer_count: 10 (number, optional, posted) - maximun count of desired transfers. Unset means undefined. If policy is TRANSFERRED count defaults to 1.
date_end: 2016-07-16T19:20:30+01:00 (string, optional, posted)- expiring date of Pull request when set for multiple transfers (with or without recurrence)
recurrence (object, optional, posted) -
- period: P2M (string, required, posted) - ISO-8061 duration representation in example "two months recurrence"
source (SourceInfo, optional, posted/returned) - money sending party identity and account. When set in pull creation the two-factor approval flow is constrainted by provided data
policy (enum, optional, posted) - controls how DropPay must act at user's approval time
- enum members
  - TRANSFERABLE - transfers will follow the Pull approval and not excuted at approval time
  - TRANSFERRED - the default, DropPay trasfers money immediately at approval time
recipient (RecipientInfo, required) - recipient party identity and account (should match against the Pull creator's one)
status (enum, required, posted)
- enum members
  - DRAFT - Pull order is still a work in progress resource and cannot be scheduled
  - READY - Pull order is ready to be granted by source party with two-factor approval flow
  - SCHEDULED - Pull order has been granted and will be executed
  - FAILED - Pull order failed and cannot generate any more transfers
  - RUNNING - Pull order is running: it has performed at least one transfer and more are to come
  - DONE - Pull order has completed its job and is not going to perform any more transfers
  - REVOKED - Pull order has been revoked by source party (coming from SCHEDULED RUNNING status)
  - CANCELLED - Pull order has been cancelled by recipient (coming from SCHEDULED, RUNNING)
  - DELETED - Pull order has been cancelled by recipient party before have been scheduled (coming from READY, DRAFT statuses)
  - REFUSED - source party has explicitly refused to grant/schedule the push order during the two-factor approval flow (coming from READY)
webhooks
- all: https://credenA:credenB@app.server.com/listener (string, optional) - listener for all Pull events available
sharing: https://dp.link/u/2/MRE1234568UN8

SourceInfo

id: BAC123456789 (string, required, returned) - Source DropPay Account Public ID
username: 3351234567 (string, optional, returned) - Source user's username
acccount_iban: IT63B3606400003351234567 (string, optional, returned) - sending account IBAN;
account: IT63B3606400003351234567 (string, optional, posted) - source DropPay account, an IBAN.
owner
- name: John Kennedy (string, optional) - source user's name
- logo: http (string, optional) - source user's logo icon if available

RecipientInfo

id: BAC123456789 (string, optional) - Recipient DropPay virtual account Public id
username: 3351234567 (string, optional, returned) - Recipient user's username if a DropPay account owner
account_iban: IT63B3606400003351234567 (string, optional) - recipient account IBAN;
account: IT63B3606400003351234567 (string, optional) - Recipient DropPay virtual account, can be an IBAN.
owner
- name: John Kennedy (string, optional) - recipient user's name
- logo: http (string, optional) - recipient user's logo icon
bank_name: Fineco Bank (string) - recipient's bank name

PullTransfer¶

PullTransfer

id: MRT1234568UN8 (string, required) - unique ID of the transfer
pull_id: MRE1234568UN8 (string, required) - unique ID of the referenced Pull
source (SourceInfo, optional) - sending party identity and account. When set in Pull creation the two-factor approval flow is constrainted by provided data
recipient (RecipientInfo, required) - recipient party identity and account
amount: 100.00 (number) - Transfer amount
fee: 1.00 (number) - DropPay service Fee
description: causale (string) - Operation narrative of the payment reason, it overrides the transfer_description of the Pull request
status: DONE (enum, required, returned) - Transaction status
- enum members
  - BOOKED
  - ACCOUNTED
  - FAILED
date_creation: 1997-07-16T19:20:30+01:00 (string) - Transfer creation date and time (ISO 8601)
date_booked: 1997-07-16T19:20:30+01:00 (string) - Transfer booking date and time (ISO 8601)
date_accounted: 1997-07-16T19:20:30+01:00 (string) - Transfer accounting date and time (ISO 8601)

REST Endpoints¶

Security¶

Requests must be authenticated with User Access Token. User Access Token can be obtained requesting it with and active Connection Code.

Details at Authentication v.1 API Reference

Webhooks & Events¶

Your Application can subscribe to the following webhooks

Webhooks

all : an URL you provide that is enabled to receive a POST with the updated Pull json payload

Add a webhook property as show below.

    "webhooks": {
        "all": "https://credenA:credenB@app.server.com/listener"
    },

Events¶

Connection Status Update¶

{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype": "pull.status_update",
    "edata": { A Pull entity }
}

Pull¶

DropPay Pull API publishes the following methods :

POST a new Push order entity to send money
GET the Push order entity to read the order status;
PATCH the Push order entity to modify the order attributes until it is set with second factor disposition protocol;
DELETE the Push order entity

POST Create a new Pull order

Create a new Pull order¶

Example¶

Request¶

curl --request POST
--url https://api.drop-pay.io/bank/v1/pull
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'

{
    "description" : "Mario's birthday gift",
    "transfer_amount": 30.00,
    "transfer_amount_policy": "FIXED",
    "policy" : "TRANSFERRED",
    "source": {
        "account": "IT63B3606400003471234567",
    },
    "status": "DRAFT",
}

Response 200

{
    "id": "MRE1234568UN8",
    "description": "Mario's birthday gift",
    "transfer_description": "Mario's birthday gift",
    "transfer_amount_policy": "FIXED",
    "policy" : "TRANSFERRED",
    "amount": 30.00,
    "date_creation": "2018-07-16T19:20:30+01:00",
    "date_last_modified": "2018-07-16T19:20:30+01:00",
    "date_scheduled": "2018-07-16T19:20:30+01:00",
    "date_recipient": "2018-10-12",
    "recipient": {
        "acccount_iban": "IT78I3606400001123456789012",
        "account": "IT78I3606400001123456789012",
        "owner": {
            "name": "Ian Solo",
        }
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT48D3606400001098765432111",
        "account": "IT48D3606400001098765432111",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "status": "DRAFT",
    "sharing": "https://dp.link/u/2/MRE1234568UN8",
}

GET Read a Pull order

Read an existent Pull order¶

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/bank/v1/pull/MRE1234568UN8
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

Response 200

{
    "id": "MRE1234568UN8",
    "description": "Mario's birthday gift",
    "transfer_description": "Mario's birthday gift",
    "transfer_amount_policy": "FIXED",
    "policy" : "TRANSFERRED",
    "amount": 30.00,
    "date_creation": "2018-07-16T19:20:30+01:00",
    "date_last_modified": "2018-07-16T19:20:30+01:00",
    "date_scheduled": "2018-07-16T19:20:30+01:00",
    "date_recipient": "2018-10-12",
    "recipient": {
        "acccount_iban": "IT78I3606400001123456789012",
        "account": "IT78I3606400001123456789012",
        "owner": {
            "name": "Ian Solo",
        }
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT48D3606400001098765432111",
        "account": "IT48D3606400001098765432111",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "status": "DRAFT",
    "sharing": "https://dp.link/u/2/MRE1234568UN8",
}

PATCH Modify a Pull order

Modify an existent Pull order¶

Example¶

Request¶

curl --request PATCH
--url https://api.drop-pay.io/bank/v1/pusll/MRE1234568UN8
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

{
    "status": "READY"
}

Response 200

{
    "id": "MRE1234568UN8",
    "description": "Mario's birthday gift",
    "transfer_description": "Mario's birthday gift",
    "transfer_amount_policy": "FIXED",
    "policy" : "TRANSFERRED",
    "amount": 30.00,
    "date_creation": "2018-07-16T19:20:30+01:00",
    "date_last_modified": "2018-07-16T19:20:30+01:00",
    "date_scheduled": "2018-07-16T19:20:30+01:00",
    "date_recipient": "2018-10-12",
    "recipient": {
        "acccount_iban": "IT78I3606400001123456789012",
        "account": "IT78I3606400001123456789012",
        "owner": {
            "name": "Ian Solo",
        }
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT48D3606400001098765432111",
        "account": "IT48D3606400001098765432111",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "status": "READY",
    "sharing": "https://dp.link/u/2/MRE1234568UN8",
}

DELETE Delete a Pull order

Delete an existent Pull order¶

Delete method changes semanthic depending upon origin status, so :

if origin status is DRAFT or READY, delete moves order to DELETED
if origin status is SCHEDULED or RUNNING, delete moves order to CANCELLED

Example¶

Request¶

curl --request DELETE
--url https://api.drop-pay.io/bank/v1/pull/MRE1234568UN8
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

Response 200

{
    "id": "MRE1234568UN8",
    "description": "Mario's birthday gift",
    "transfer_description": "Mario's birthday gift",
    "transfer_amount_policy": "FIXED",
    "policy" : "TRANSFERRED",
    "amount": 30.00,
    "date_creation": "2018-07-16T19:20:30+01:00",
    "date_last_modified": "2018-07-16T19:20:30+01:00",
    "date_scheduled": "2018-07-16T19:20:30+01:00",
    "date_recipient": "2018-10-12",
    "recipient": {
        "acccount_iban": "IT78I3606400001123456789012",
        "account": "IT78I3606400001123456789012",
        "owner": {
            "name": "Ian Solo",
        }
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT48D3606400001098765432111",
        "account": "IT48D3606400001098765432111",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "status": "DELETED",
    "sharing": "https://dp.link/u/2/MRE1234568UN8",
}

Pull Transfers¶

DropPay Pull Transfer API publishes the following methods :

POST a new Transfer entity to pull money
GET the Pull Transfer entity to read its status;

POST Execute a Pull Transfer

Example¶

Request¶

curl --request POST
--url https://api.drop-pay.io/bank/v1/pull/{id_pull}/transfer/
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

URL Parameters

id_pull: MRT1234568UN8 - unique ID of the Pull order

{
    "description" : "Mario's birthday gift",
    "amount": 30.00,
}

Response 200

    {
        "id": "MRT1234568UN8",
        "pull_id": "MRE1234568UN8",
        "amount": 30.00,
        "description": "Mario's birthday gift",
        "source": {
            "id": "BAC123456789",
            "username": "3351234567",
            "account_iban": "IT48D3606400001098765432111",
            "account": "IT48D3606400001098765432111",
            "owner": {
                "name": "John Kennedy",
            }
        },
        "recipient": {
            "acccount_iban": "IT78I3606400001123456789012",
            "account": "IT78I3606400001123456789012",
            "owner": {
                "name": "Ian Solo",
            }
        },
        "status": "ACCOUNTED",
        "date_creation": "1997-07-16T19:20:30+01:00",
        "date_booked": "1997-07-16T19:20:30+01:00",
        "date_accounted": "1997-07-16T19:20:30+01:00",
    }

Response 400

    {
        "code": "100",
        "description": "Missing arguments"
    }

GET Read a specific Pull Transfer

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/bank/v1/pull/{id_pull}/transfer/{id_pull_transfer}
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

URL Parameters

id_pull: MRT1234568UN8 - unique ID of the Pull order
id_pull_transfer: MRT1234568UN8 - unique ID of the Pull order

Response 200

    {
        "id": "MRT1234568UN8",
        "pull_id": "MRE1234568UN8",
        "amount": 30.00,
        "description": "Mario's birthday gift",
        "source": {
            "id": "BAC123456789",
            "username": "3351234567",
            "account_iban": "IT48D3606400001098765432111",
            "account": "IT48D3606400001098765432111",
            "owner": {
                "name": "John Kennedy",
            }
        },
        "recipient": {
            "acccount_iban": "IT78I3606400001123456789012",
            "account": "IT78I3606400001123456789012",
            "owner": {
                "name": "Ian Solo",
            }
        },
        "status": "ACCOUNTED",
        "date_creation": "1997-07-16T19:20:30+01:00",
        "date_booked": "1997-07-16T19:20:30+01:00",
        "date_accounted": "1997-07-16T19:20:30+01:00",
    }

Response 400

    {
        "code": "100",
        "description": "Missing arguments"
    }

GET Listing Pull Transfers

Listing Pull Transfers¶

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/bank/v1/pull/{id}/transfers{?iban,role,status,description,date_from,date_to,pg_num,pg_size}]
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

URL Parameters

id: MRE1234568UN8 - unique ID of the Pull order (-1 if you want trasfers of all pushes)
iban: IT123456789 - iban the Pulls refer to
role: ALL|SOURCE|RECIPIENT - Iban's role for the Pulls
status: BOOKED, TRANSFER, FAILED - Transfer's statuses csv
description: (string, optional)
date_from: 1997-07-16T19:20:30+01:00 (string, optional)
date_to: 1997-07-16T19:20:30+01:00 (string, optional)
pg_num: 0 (number)
pg_size: 100 (number)

Response 200

{
    "transfers": [
        {},
        {},
        {}
    ],
    "paging_info": {
        "current_page": 0,
        "total_pages": 1,
        "page_size": 100,
        "total_items": 3,
        "items_offset": 1
    }
}

Response 400

    {
        "code": "100",
        "description": "Missing arguments"
    }