Skip to content

DropPay API - Bank v.1 - Push

You may want to send money to another DropPay account or to any other bank account in SEPA area.

DropPay offers an API to accomplish this: the Push API.

With Push API your application can:

1️⃣ send an amount of money to another DropPay account

2️⃣ send an amount of money to another Bank Account in SEPA Area

3️⃣ send an amount of money for N times with a specified recurring period

4️⃣ send an amount of money with a specified recurring period until a specified date

Submitting a Push

A Push is a RESTful entity. It is created with a POST and it persists on DropPay server side. When submitting the Push you will receive a sharing attribute containing 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.

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

Push entity does not represent the money transfer operation but its control resource. Actual money transfer is kept by Transfer REST entity. A Push can allow to execute a single Transfer or a list of Transfers.

Using Push for money trasfers between DropPay accounts

Push always requires you to set a recipient IBAN. When IBAN is detected to correspond to an A-Tono Payment Institute account, DropPay will perform a transfer within the Payment Institute.

You can submit a DropPay transfer at any time during the 24 hours, but available balance is charged accordingly and immediately at date_scheduled (please read below the section "Scheduling Push"). A-Tono Payment Institute considers a Push order received when time is equal to date_scheduled.

Here below a minimal json payload to initiate a money transfer toward another DropPay account.

Currency is Euro (€).

1
2
3
4
5
6
7
8
{
    "amount": 120.00,
    "recipient": {
        "account": "IT63B3606400003471234567",
    },
    "status": "READY"

}

Using Push for SCT SEPA Money Trasfers

Push always requires you to set a recipient IBAN. When IBAN is detected not to correspond to any A-Tono Payment Institute account, DropPay will perform a SEPA SCT.

You can submit a SEPA SCT at any time during the 24 hours, but available balance is charged accordingly and immediately at date_scheduled (please read below the section "Scheduling Push execution"). A-Tono Payment Institute considers a Push order received when time is equal to date_scheduled.

Here below a minimal json payload to initiate a money transfer toward another DropPay account.

Currency is Euro (€).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "amount": 120.00,
    "recipient": {
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach"
        }
    },
    "status": "READY"

}

Cut Off time

SCT scheduled today between 00:00:00 and 10:14:59 will be trasmitted to SEPA circuit at 10:30:00 of today unless today is a closing day. If so, it will be transmitted at 10:30 of the first future operative day.

SCT scheduled today between 10:15:00 and 23:59:59 will be trasmitted to SEPA circuit at 10:30:00 of tomorrow unless tomorrow is a closing day. If so, it will be transmitted at 10:30 of the first future operative day.

Please refer to SEPA Target closing days for further informations

Scheduling Push execution

Push is created by default in DRAFT state. In that state nothing will happen and any attempt to approve the sharing link with the second-factor DropPay mobile app will result in an error.

When set to READY, you may have already set a date_schedule value or not. All date_schedule values earlier than the current date-time will result in an immediate Push scheduling then available balance is charged (unless it is to short to enable the transfer) and :

  • if you're pushing to a DropPay account , the transfer is immediately accounted
  • if you're pushing to SEPA circuit, the transfer is embargoed for the first available cut off

When date_scheduled is a date-time in the future, available balance is NOT charged, the operation is scheduled to be received and exceuted at the date chosen.

Here below an example of json payload (let's say current time is 2018-05-20 08:00:00):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "amount": 120.00,
    "recipient": {
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach"
        }
    },
    "status": "READY",
    "date_scheduled": "2018-06-15 10:00:00"

}

Perform recurring transfers

Push can be used for execute a single money transfer or to schedule a list of transfers recurring with a defined time period.

You can define:

  • the time period, an ISO 8601 compliant duration string;
  • the end date-time of recurring transfers;
  • the number of transfers to be executed;

The following json payload sets a SEPA SCT to be executed every 2 from June the 6th 2018 to July the 10th 2019 months.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "amount": 120.00,
    "recipient": {
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach"
        }
    },
    "status": "READY",
    "date_scheduled": "2018-06-15 10:00:00",
    "recurrence":{
        "period": "P2M",
        "date_end": "2019-07-10T00:00:00"
    }

}

Please remember that cut off rules don't change when recurrence settings are present. SEPA Target calendar applies in SCT push operations.


Warning

Your application must act on behalf of the DropPay account owner who is the source party of the Push you want to perform.

Read Connection API reference first!


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

Push
  • id: SEM1234568UN8 (string, returned) - Unique ID of the push order
  • description: my label (string, optional, posted) - Description of the push order
  • transfer_description: my label (string, optional, posted) - Description of the reason of the single transfer the Push order is issueing
  • amount: 50.00 (number, required, posted) - Amount of money to be transferred
  • fee: 0.99 (number, returned) - Service fee
  • date_creation: 2016-07-16T19:20:30+01:00 (string, returned) - Date the Push order has been POSTed
  • date_last_modified: 2016-07-16T19:20:30+01:00 (string, returned)- Last date the Push order has been modified
  • date_scheduled: 2016-07-16T19:20:30+01:00 (string, returned)- Planned date of the very first transfer's execution
  • date_recipient: 2016-10-12 (string, returned)- Reecipient accounting date (useful only in SEPA/SCT operation )
  • recurrence (object, optional, posted)
    • period: P2M (string, required, posted) - ISO8061 duration representation (in this example "two months recurrence")
    • count: 10 (number, optional, posted) - Number of desired recurrences. Unset this to let the count undefined.
    • date_end: 2016-07-16T19:20:30+01:00 (string, posted)- Recurrence end date
  • source (SourceInfo, optional, posted/returned) - Money sending identity and account.
  • recipient (RecipientInfo, required, posted) - Recipient data
  • status (enum, required, returned/posted)
    • enum members
      • DRAFT - push order is still a work in progress resource and cannot be scheduled
      • READY - push order is ready to be scheduled (approved) with second factor disposition protocol
      • SCHEDULED - push order has been scheduled (approved) and will be executed at date_scheduled
      • FAILED - push order failed and cannot generate any more transfers
      • RUNNING - push order is running: it has performed at least one transfer and more are to come
      • DONE - push order has completed its job and is not going to perform any more transfers
      • REVOKED - push order has been revoked by user after have been performed at least a transfer (coming from RUNNING status)
      • CANCELLED - push order has been cancelled before having performed any transfer (coming from SCHEDULED)
      • DELETED - push order has been cancelled before have been scheduled (coming from READY, DRAFT statuses)
      • REFUSED - user has explicitly refused to schedule the push order during the second factor disposition flow
      • FAILURE - when a batched push is not validated, not saved and the status_description attribute is valued
      • WAITING_APPROVAL - SEPA SCT higher than 1.500,00€ will be stopped waiting for A-Tono Payment Institute backoffice approval
      • NOT_APPROVED - SEPA SCT amount was higher than 1.500,00€ and has been stopped by A-Tono Payment Institute backoffice
  • webhooks
    • all: https://credenA:credenB@app.server.com/listener (string, optional, posted) - your listener endpoint (port 80 or 443) for all Push events
  • sharing: https://dp.link/u/2/SEM1234568UN8 (string, required, returned)
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
PushTransfer
  • id: SMP1234568UN8 (string, required, returned) - unique ID of the transfer
  • push_id: SEM1234568UN8 (string, required, returned) - unique ID of generating Push
  • source (SourceInfo, optional, returned) - Sending identity and account.
  • recipient (RecipientInfo, required, returned) - Recipient party identity and account
  • amount: 100.00 (number, required,posted) - Transfer amount
  • fee: 1.00 (number, required,returned) - DropPay service Fee
  • description: the reason (string, required, posted) - Operation narrative of the payment reason
  • status: DONE (enum, required, returned) - Status of transfer execution
    • enum members
      • BOOKED
      • ACCOUNTED
      • FAILED
  • trnid: 3606400020619212480160001600IT (string) - Transaction ID if SEPA SCT
  • date_creation: 1997-07-16T19:20:30+01:00 (string) - Transfer creation date and time (ISO 8601)
  • date_accounted: 1997-07-16T19:20:30+01:00 (string) - Transfer accounting date and time (ISO 8601)
  • date_recipient: 2016-10-12 (string) - Transfer settlement 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

Push

DropPay Push 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 Push order

Create a new Push order

Example

⬆️ Request
1
2
3
4
curl --request POST
--url https://api.drop-pay.io/bank/v1/push
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "amount": 120.00,
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
        "recipient": {
            "account": "IT60X0542811101000000123456",
            "owner": {
                "name": "Edward Teach"
            }
        },
    "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
31
32
33
34
35
{
    "id": "SEM1234568UN8",
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "amount": 120.00,
    "fee": 1.00,
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16T19:20:30+01:00",
    "date_recipient": "2016-10-12",
    "recurrence": {
        "period": "P2M",
        "count": 10,
        "date_end": "2016-07-16T19:20:30+01:00"
    },
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "account": "IT63B3606400003351234567",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "status": "DRAFT",
    "sharing": "https://dp.link/u/2/SEM1234568UN8",
}
GET Read a Push order

Read an existent Push order

Example

⬆️ Request
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
31
32
33
34
35
36
{
    "id": "SEM1234568UN8",
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "amount": 120.00,
    "fee": 1.00,
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16T19:20:30+01:00",
    "date_recipient": "2016-10-12",
    "recurrence": {
        "period": "P2M",
        "count": 10,
        "date_end": "2016-07-16T19:20:30+01:00"
    },
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "account": "IT63B3606400003351234567",
        "owner": {
            "name": "John Kennedy",
            "logo": "url://"
        }
    },
    "status": "DRAFT",
    "sharing": "https://dp.link/u/2/SEM1234568UN8",
}
Response 400
1
2
3
4
    {
        "code": "100",
        "description": "Missing arguments"
    }
PATCH Modify a Push order

Modify an existent Push order

Example

⬆️ Request
1
2
3
curl --request PATCH
--url https://api.drop-pay.io/bank/v1/push/SEM145123G6YY
--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
31
32
33
34
35
36
{
    "id": "SEM1234568UN8",
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "amount": 120.00,
    "fee": 1.00,
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16T19:20:30+01:00",
    "date_recipient": "2016-10-12",
    "recurrence": {
        "period": "P2M",
        "count": 10,
        "date_end": "2016-07-16T19:20:30+01:00"
    },
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "account": "IT63B3606400003351234567",
        "owner": {
            "name": "John Kennedy",
            "logo": "url://"
        }
    },
    "status": "READY",
    "sharing": "https://dp.link/u/2/SEM1234568UN8",
}
Response 400
1
2
3
4
    {
        "code": "100",
        "description": "Missing arguments"
    }
DELETE Delete a Push order

Delete an existent Push 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, delete moves order to CANCELLED
  • if origin status is RUNNING, delete moves order to REVOKED

Example

⬆️ Request
1
2
3
curl --request DELETE
--url https://api.drop-pay.io/bank/v1/push/SEM145123G6YY
--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
31
32
33
34
35
36
{
    "id": "SEM1234568UN8",
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "amount": 120.00,
    "fee": 1.00,
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16T19:20:30+01:00",
    "date_recipient": "2016-10-12",
    "recurrence": {
        "period": "P2M",
        "count": 10,
        "date_end": "2016-07-16T19:20:30+01:00"
    },
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "account": "IT63B3606400003351234567",
        "owner": {
            "name": "John Kennedy",
            "logo": "url://"
        }
    },
    "status": "DELETED",
    "sharing": "https://dp.link/u/2/SEM1234568UN8",
}
Response 400
1
2
3
4
    {
        "code": "100",
        "description": "Missing arguments"
    }

Push Listing

DropPay Push API publishes the following listing method :

  • GET the list of Push order entities to read the order status;
GET Listing Pushes

Listing Pushes

1
2
3
    curl --request GET
    --url https://api.drop-pay.io/bank/v1/pushes/{?iban,status,description,type,date_from,date_to,order_by,order_dir,pg_num,pg_size}
    --header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
URL Parameters
  • iban: IT123456789 - iban the pushes refer to
  • status: DRAFT,READY,... - Push's statuses csv
  • description: (string, optional)
  • type: SCT|DPCT (string, optional) - Sct or DropPay Credit Transfer
  • date_from: 1997-07-16T19:20:30+01:00 (string, optional)
  • date_to: 1997-07-16T19:20:30+01:00 (string, optional)
  • order_by: (enum, optional)
    • enum members
      • date_creation:
      • date_schedule:
  • order_dir: (enum, optional)
    • enum members
      • asc
      • desc
  • pg_num: 0 (number)
  • pg_size: 100 (number)
Response 200
⬇️ Response 200
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
   "pushes": [
       {},
       {},
       {}
   ]
    "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"
    }

Push Transfers

GET Read a specific Push Transfer

Example

Request
1
2
3
curl --request GET
--url https://api.drop-pay.io/bank/v1/push/transfer/SMP145123G6YY
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
URL Parameters
  • id: SMP145123G6YY - unique ID of the push 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
27
28
29
30
31
{
    "id": "SMP1234568UN8",
    "push_id": "SEM1234568UN8",
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Ocracoke Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "account": "IT63B3606400003351234567",
        "owner": {
            "name": "John Kennedy",
            "logo": "url://"
        }
    },
    "amount": 120,
    "fee": 1,
    "description": "Sending money / first payment",
    "status": "BOOKED",
    "trnid": "3606400020619212480160001600IT",
    "date_creation": "1997-07-16T19:20:30+01:00",
    "date_accounted": "1997-07-16T19:20:30+01:00",
    "date_recipient": "2016-10-12"

}
Response 400
1
2
3
4
    {
        "code": "100",
        "description": "Missing arguments"
    }
GET Listing Push Transfers

Listing Push Transfers

Example

Request
1
2
3
curl --request GET
--url https://api.drop-pay.io/bank/v1/push/{id}/transfers{?iban,role,status,description,type,date_from,date_to,pg_num,pg_size}]
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
URL Parameters
  • id: SEM145123G6YY - unique ID of the push order (-1 if you want trasfers of all pushes)
  • status: BOOKED, TRANSFER, FAILED - Transfer's statuses csv
  • description: (string, optional)
  • type: SCT|DPCT (string, optional) - SEPA or DropPay Credit Transfer
  • 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
15
16
17
##### :arrow_down: Response ==200==
``` json
{
     "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"
    }