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:

send an amount of money to another DropPay account

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

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

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 (€).

{
    "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 (€).

{
    "amount": 120.00,
    "recipient": {
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach"
        }
    },
    "status": "READY"

}

Cut Off time

SCT scheduled between 00:00:00 and 23:59:59 will be trasmitted to SEPA circuit at 10:30:00 of the next business 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):

{
    "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 6^th 2018 to July the 10^th 2019 months.

{
    "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 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

Push¶

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 requesting 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¶

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

{
    "amount": 120.00,
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
        "recipient": {
            "account": "IT60X0542811101000000123456",
            "owner": {
                "name": "Edward Teach"
            }
        },
    "status": "DRAFT"
}

Response 200

{
    "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¶

curl --request GET
--url https://api.drop-pay.io/bank/v2/push/SEM1234568UN8
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

Response 200

{
    "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

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

PATCH Modify a Push order

Modify an existent Push order¶

Example¶

Request¶

curl --request PATCH
--url https://api.drop-pay.io/bank/v2/push/SEM145123G6YY
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

{
    "status": "READY"
}

Response 200

{
    "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

    {
        "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¶

curl --request DELETE
--url https://api.drop-pay.io/bank/v2/push/SEM145123G6YY
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

Response 200

{
    "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

    {
        "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¶

    curl --request GET
    --url https://api.drop-pay.io/bank/v2/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¶

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

}

Response 400

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

Push Transfers¶

GET Read a specific Push Transfer

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/bank/v2/push/transfer/SMP145123G6YY
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

URL Parameters

id: SMP145123G6YY - unique ID of the push order

Response 200

{
    "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

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

GET Listing Push Transfers

Listing Push Transfers¶

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/bank/v2/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

##### :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

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