Skip to content

DropPay PSD2 - TPP API - Payment Initiation

You may want to perform a payment toward 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

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 he wants to enable the payment through the two-factor disposition flow.

Push entity is created by server in DRAFT status and must be put in READY status if you want to enable user to confirm it with the 2nd-factor app. You can create a Push already in READY status (setting it explicitly in the POST payload) or you can update it in DRAFT status until you need to.

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

Using Push for money trasfers between DropPay accounts

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

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 valid A-Tono Payment Institute account, DropPay will perform a SEPA SCT.

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 today between 00:00: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 working 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.

Setting status to READY 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 cycle.

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",
}

Verifing the Push operation feasibility

Regulation References

COMMISSION DELEGATED REGULATION (EU) 2018/389

CHAPTER V - COMMON AND SECURE OPEN STANDARDS OF COMMUNICATION

Section 2 - Specific requirements for the common and secure open standards of communication

Article 36 - Data exchanges

1: Account servicing payment service providers shall comply with each of the following requirements:

c: they shall, upon request, immediately provide payment service providers with a confirmation in a simple ‘yes’ or ‘no’ format, whether the amount necessary for the execution of a payment transaction is available on the payment account of the payer.

Before submitting a push, you may need to verify the user's account's balance is available for the operation's success.

As long as current fees configuration is subjected to commercial conditions agreed between user and A-Tono Payment Institute, the payment operation should be not free and a fee applied at run time.

TPP is reccomended to verify the Push operation before submitting it.

Verifing a Push will perform as all the validations and check as DropPay would do when a real Push is submitted, but without storing and executing it.

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

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 issuing (if different from push order description)
  • amount: 50.00 (number, required, posted) - Amount of money to be transferred
  • 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 )
  • source (SourceInfo, optional, posted/returned) - Money sending identity and account.
  • recipient (RecipientInfo, required, posted) - Recipient data
  • status (enum, required, returned/posted)
    • enumerated 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
  • 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
RecipientInfo
  • 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, required, posted) - Recipient DropPay virtual account, can be an IBAN.
  • owner
    • name: John Kennedy (string, optional) - recipient user's name
  • 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
  • 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 an Access Token. Access Token can be obtained performing the authentication request as decribed in PSD2 - TPP on-boarding page.

Push

DropPay Push API offers 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/v1/push
--header 'authorization: Bearer <access token>'
--header 'content-type:application/json'

{
    "amount": 120.00,
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "recipient": {
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach"
        }
    },
    "source": {
        "account": "IT86M3606400001393351234567"
    }
}
Response 200 
{
    "id": "SEM1234568UN8",
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "amount": 120.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",
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT86M3606400001393351234567",
        "account": "IT86M3606400001393351234567",
        "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/v1/push/SEM1234568UN8
--header 'Authorization: Bearer <access token>'
Response 200 
{
    "id": "SEM1234568UN8",
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "amount": 120.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",
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        },
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT86M3606400001393351234567",
        "account": "IT86M3606400001393351234567",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "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/v1/push/SEM145123G6YY
--header 'authorization: Bearer <access token>'

{
    "status": "READY"
}
Response 200 
{
    "id": "SEM1234568UN8",
    "description": "Sending money",
    "transfer_description": "Sending money / first payment",
    "amount": 120.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",
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        },
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT86M3606400001393351234567",
        "account": "IT86M3606400001393351234567",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "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/v1/push/SEM145123G6YY
--header 'authorization: Bearer <access token>'
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",
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT86M3606400001393351234567",
        "account": "IT86M3606400001393351234567",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "status": "DELETED",
    "sharing": "https://dp.link/u/2/SEM1234568UN8",
}
Response 400 
    {
        "code": "100",
        "description": "Missing arguments"
    }

Push Transfers

DropPay Push Transfers API offers the following methods :

  • GET a trasfer
GET Read a specific Push Transfer

Example

Request
curl --request GET
--url https://api.drop-pay.io/bank/v1/push/transfer/SMP145123G6YY
--header 'authorization: Bearer <access token>'
URL Parameters
  • id: SMP145123G6YY - unique ID of the push transfer
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": "IT86M3606400001393351234567",
        "account": "IT86M3606400001393351234567",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "amount": 120,
    "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 a specific Push Transfers

Listing Push Transfers

Example

Request
curl --request GET
--url https://api.drop-pay.io/bank/v1/push/{id}/transfers
--header 'authorization: Bearer <access token>'
Response 200 
##### :arrow_down: Response ==200==
``` json
{
     "transfers": [
         {},
     ],
}
```
Response 400 
    {
        "code": "100",
        "description": "Missing arguments"
    }

Push Verification

DropPay Push Verification API offers the following methods :

  • POST a Push to simulate its feasibility
POST Verify the feasibility of a Push order

Verify the feasibility of a Push order

Example

⬆ Request
curl --request POST
--url https://api.drop-pay.io/bank/v1/push/verify
--header 'authorization: Bearer <access token>'
--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,
    "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",
    "recipient": {
        "acccount_iban": "IT60X0542811101000000123456",
        "account": "IT60X0542811101000000123456",
        "owner": {
            "name": "Edward Teach",
        }
        "bank_name": "Fineco Bank"
    },
    "source": {
        "id": "BAC123456789",
        "username": "3351234567",
        "account_iban": "IT86M3606400001393351234567",
        "account": "IT86M3606400001393351234567",
        "owner": {
            "name": "John Kennedy",
        }
    },
    "status": "DRAFT",
    "sharing": "https://dp.link/u/2/SEM1234568UN8",
}