Skip to content

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "description" : "Bike purchase instalment payment"
    "transfer_amount": 200.00,
    "transfer_amount_policy": "FIXED",
    "transfer_count": 60,
    "policy" : "TRANSFERABLE"
    "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.

1
2
3
4
    {
        "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 a property value
  • (type, returned) is the type of a returned property
  • (type, posted) is the type of a requested property
  • after the dash "-" there's the attribute description

name: example_value (type, direction) - Property description

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

???- summary "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

???- summary "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
  • 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 requestin 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.

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

Events

Connection Status Update
1
2
3
4
5
{
    "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
1
2
3
4
curl --request POST
--url https://api.drop-pay.io/bank/v1/pull
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "description" : "Mario's birthday gift",
    "transfer_amount": 30.00,
    "transfer_amount_policy": "FIXED",
    "policy" : "TRANSFERRED",
    "source": {
        "account": "IT63B3606400003471234567",
    },
    "status": "DRAFT",
}
Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "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
1
2
3
curl --request GET
--url https://api.drop-pay.io/bank/v1/pull/MRE1234568UN8
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "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
1
2
3
curl --request PATCH
--url https://api.drop-pay.io/bank/v1/pusll/MRE1234568UN8
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
1
2
3
{
    "status": "READY"
}
Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "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
1
2
3
curl --request DELETE
--url https://api.drop-pay.io/bank/v1/pull/MRE1234568UN8
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "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
1
2
3
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
1
2
3
4
{
    "description" : "Mario's birthday gift",
    "amount": 30.00,
}
Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
    {
        "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
1
2
3
4
    {
        "code": "100",
        "description": "Missing arguments"
    }
GET Read a specific Pull Transfer

Example

Request
1
2
3
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
    {
        "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
1
2
3
4
    {
        "code": "100",
        "description": "Missing arguments"
    }
GET Listing Pull Transfers

Listing Pull Transfers

Example

Request
1
2
3
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "transfers": [
        {},
        {},
        {}
    ],
    "paging_info": {
        "current_page": 0,
        "total_pages": 1,
        "page_size": 100,
        "total_items": 3,
        "items_offset": 1
    }
}
Response 400
1
2
3
4
    {
        "code": "100",
        "description": "Missing arguments"
    }