DropPay API - Bank v.1 - ISO 20022 Messages - Customer Credit Transfer Initiation (PAIN.001)¶

Part of the Single Euro Payment Area (SEPA) legislation is the introduction of a new file format for payment initiation: the PAIN.001 format.

PAIN.001 file batches are XML files that must be structured according to the XML Schema Definition (XSD) pain.001.001.03 that is the recommended version from the European Payment Council, EPC.

A PAIN.001.001.003 (CustomerCreditTransferInitiation) XML file is transmitted posting a job through DropPay Restful API and a PAIN.002.001.003 XML is returned (CustomerPaymentStatusReport) as results when errors or exceptions are raised.

The PAIN.001.001.003 XML file must be embodied in a json payload as escaped string attribute.

How it works¶

In order to get payments executed with a PAIN 001 you have to:

POST a request that initializes a job with desired parameters in a json object; formal validation is immediately performed on input items and an unique ID is returned along with other server valued attributes;
PATCH the job resource until you think it's ready to be launched;
make the job run (PATCH the status to be READY) and wait for it to complete while catching the event your client has been subscribed to.

Data validation

Plese remember that PAIN.001 XML contents are evaluated only when you PATCHthe status to READY asking DropPay to process the payments. Status can be READY since the very first post too, when creating the job. This is the case when you post the request all in once.

PAIN 001 and PAIN 002 DropPay specification¶

You can find XML schemas specified as a formatted table in the documents

Here below some addictional notes:

Unique Message ID¶

The field MsgId in the group header of PAIN.001 files must be unique for each submitted file. The field is used to avoid duplicates: i.e., when a file is re-submitted, then it is rejected based on the occurrence of a duplicate message ID. Customers are free to apply their own method of choosing unique message ID’s. Typically message ID’s are system-generated sequential numbers (001, 002 etc.), sometimes prefixed by the date (2014-02-11-001, 2014-02-11-002, etc.). The restriction that is imposed by the XML Schema Definition (XSD) is that the length of message ID’s may not exceed 35 characters. The message ID is mapped to the Client Reference Number.

Payment Information Blocks¶

A PAIN.001 file must contain at least one Payment information block (PmtInf. In most cases PAIN.001 files contain only one block, with one set of payment instructions. The purpose of grouping payments in separate PmtInf blocks is the following. General properties, such as the execution date, the debtor, the debited account and the debtor agent are stated once, at the level of the PmtInf block. That way, the payment information of separate transactions can be briefer. Please remember that DropPay allows only to debit the account your client is connected with. See details at Connection v.1 API Reference.

Payment Information: Requested Execution Date¶

Each PmtInf block has its own Requested Execution Date, ReqdExctnDt. It is thereby possible to create e.g. one file with two payment information blocks, each with a different date. For every payment in its PmtInf group, affected by the stated requested execution date, the date is mapped to the payment’s requested execution date, its value date, and its release date.

PAIN 001 Versioning¶

Currently DropPay supports only Version 3 of PAIN 001.

Anyway if any other version compliance will be added in the future, you'll be able to request DropPay to process PAIN 001 intiation files accordingly with the version set as job attribute.

    "version": "001.003",

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

PAIN 001.001¶

PAIN 001.001

id: ISO145123G6YY (string, returned) - Unique job identifier, returned by the server
date_creation: 2016-07-16T19:20:30+01:00 (string, returned) - ISO 8601 time representation of job creation timestamp
date_last_modified: (string, returned) - 2016-07-16T19:20:30+01:00- Last date the form has been modified
date_scheduled: (string, returned) -2016-07-16- Date the job has been executed
version:
- initiation: 001.003 (enum, optional, posted, returned) - indication of ISO 20022 supported version of XML posted for initiation
  - enum members
    - 001.003
- report: 001.003 (enum, optional, posted, returned) - requested ISO 20022 supported version of XML report
  - enum members
    - 001.003
initiation: (string, required, posted) - Escaped XML string of a pain.001 schema file
report: - PAIN.001.002 report is appended to this list when available. + date_issued: 2016-07-16T19:20:30+01:00 (string) - ISO 8601 time representation of report updating date + url: https://api.drop-pay.io/bank/iso20022/v1/pain/002/ISO145123G6YY.xml - download URL of the report (a PAIN.001.002 XML string). Filename is built with a DropPay ID username and a timestamp
amount: 50.00 (number) - total amount of all requested transfers
fee: 8.00 (number) - total fee of the batch
description: my label (string, optional) - free description of requested job
iban: IT00A1000010000393471122333 (string, required) - bank account IBAN
status: (enum, required) - status shortly remapped from PushBatch API structure
- enum members
  - DRAFT - job order is still a work in progress resource and cannot be scheduled
  - VALIDATING - trasitional state during which system is deeply validating transfer data
  - READY - job order is ready to be scheduled with disposition protocol
  - REFUSED - user has explicitly refused to authorize the job order during the disposition flow with second-factor DropPay
  - SCHEDULED - job order has been scheduled and will be executed
  - RUNNING - job order is running: it has performed at least a payment and more are to come
  - DONE - job order has completed its work and is not going to perform any more payment
  - REVOKED - job order has been revoked by user after have been performed at least a payment (coming from RUNNING status)
  - CANCELLED - job order has been cancelled before having performed any payment (coming from SCHEDULED, READY, DRAFT status)
  - DELETED - job order has been cancelled before have been scheduled (coming from READY, DRAFT statuses)
sharing: https://dp.link/u/2/PSB1234568UN8 - sharing link of job for authorization purposes
progress:
- count: 10 (number) - number of processed payments
- of: 15 (number) - number of requested payments
webhooks:
- pain001: https://credenA:credenB@app.server.com/listener (string, optional) - listener for Pain001 job events

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

Manage PAIN 001 jobs¶

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 PAIN 001 job

Create a new PAIN 001 job¶

At your first POST only iban attribute is required to save the job in a DRAFT state.

Then you can PATCH it up filling optional data as description, webhooks and version: the job will remain in DRAFTstate.

Only when the attribute initiation, valued with an PAIN 001.001.003 XML string is passed in, DropPay will run a validation process replying with a response containing the job json representation:

if the validation has been successful the status is still DRAFT and report attribute is unset
if the validation has failed the status is DISCARDED an XML PAIN.002.001.003 has been produced and its download URL is available in the report attribute.

DISCARDED Status

When your job has been DISCARDED, you must create a new one as long as DropPay will have been closed it.

The `READY` status¶

DropPay will load the job and execute it only when status attribute is set to READY. Setting the status to READY it's up to your client.

You can decide to PATCH only the status attribute once the PAIN.001 has been validated and the job was in DRAFT status, or you can pass in a json payload completed with all job's required data with the very first POST, and status valued with READY too.

If so, DropPay will validate the whole request and will attempt to process the initiation, replying with a response containing the job json representation:

if the validation has been successful the status is still READY and report attribute is unset
if the validation has failed the status is DISCARDED an XML PAIN.002.001.003 has been produced and its download URL is available in the report attribute.

Example¶

Request¶

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

{
    "description" : "monthly payments",
    "initiation" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn><GrpHdr><MsgId>ABC/090928/CCT001<\/MsgId><CreDtTm>2009-09-28T14:07:00<\/CreDtTm><NbOfTxs>3<\/NbOfTxs><CtrlSum>0.20<\/CtrlSum><InitgPty><Nm>ABC Corporation<\/Nm><PstlAdr><StrtNm>Times Square<\/StrtNm><BldgNb>7<\/BldgNb><PstCd>NY 10036<\/PstCd><TwnNm>New .... <\/Document>",
    "date_scheduled" : "2018-07-30",
    "webhooks" : {
        "pain001": "https://credenA:credenB@app.server.com/listener",
    },
}

Response 200 - No Errors in payments : status DRAFT

Response 200¶

{
    "id" : "ISO145123G6YY",
    "date_creation" : "2016-07-16T19:20:30+01:00",
    "date_last_modified" : "2016-07-16T19:20:30+01:00"
    "description" : "monthly payments",
    "initiation" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn><GrpHdr><MsgId>ABC/090928/CCT001<\/MsgId><CreDtTm>2009-09-28T14:07:00<\/CreDtTm><NbOfTxs>3<\/NbOfTxs><CtrlSum>0.20<\/CtrlSum><InitgPty><Nm>ABC Corporation<\/Nm><PstlAdr><StrtNm>Times Square<\/StrtNm><BldgNb>7<\/BldgNb><PstCd>NY 10036<\/PstCd><TwnNm>New .... <\/Document>",
    "date_scheduled" : "2018-07-30",
    "webhooks" : {
            "pain001": "https://credenA:credenB@app.server.com/listener",
    },
    "version" : {
        "initiation" : "001.003",
        "report" : "001.003",
    },
    "status" : "DRAFT",
    "amount" : 50.00,
    "fee" : 8.00,
    "sharing" : "https://dp.link/u/2/ISO145123G6YY",
    "progress" : {
        "count" : 0,
        "of" : 15
    }
}

Response 200 - Errors in Payments: status DISCARDED

Response 200¶

{
    "id" : "ISO145123G6YY",
    "date_creation" : "2016-07-16T19:20:30+01:00",
    "date_last_modified" : "2016-07-16T19:20:30+01:00",
    "description" : "monthly payments",
    "initiation" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn><GrpHdr><MsgId>ABC/090928/CCT001<\/MsgId><CreDtTm>2009-09-28T14:07:00<\/CreDtTm><NbOfTxs>3<\/NbOfTxs><CtrlSum>0.20<\/CtrlSum><InitgPty><Nm>ABC Corporation<\/Nm><PstlAdr><StrtNm>Times Square<\/StrtNm><BldgNb>7<\/BldgNb><PstCd>NY 10036<\/PstCd><TwnNm>New .... <\/Document>",
    "date_scheduled" : "2018-07-30",
    "webhooks" : {
        "pain001": "https://credenA:credenB@app.server.com/listener",
    },
    "version" : {
        "initiation" : "001.003",
        "report" : "001.003",
    },
    "status" : "DISCARDED",
    "report" : {
        "date_issued" : "2016-07-16T19:20:30+01:00",
        "url" : "https://api.drop-pay.io/bank/iso20022/v1/pain/002/ISO145123G6YY.xml",
    }
    "amount" : 50.00,
    "fee" : 8.00,
    "sharing" : "https://dp.link/u/2/ISO145123G6YY",
    "progress" : {
        "count" : 0,
        "of" : 15,
    }
}

PATCH Create a new PAIN 001 job

Update a PAIN 001 job¶

Example¶

Request¶

curl --request PATCH
--url https://api.drop-pay.io/bank/iso20022/v1/pain/001/ISO145123G6YY
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'

URL Parameters

id: ISO145123G6YY - Unique ID of the job

{
    "status" : "READY"
}

Response 200

Response 200¶

{
    "id" : "ISO145123G6YY",
    "date_creation" : "2016-07-16T19:20:30+01:00",
    "date_last_modified" : "2016-07-16T19:20:30+01:00",
    "description" : "monthly payments",
    "initiation" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn><GrpHdr><MsgId>ABC/090928/CCT001<\/MsgId><CreDtTm>2009-09-28T14:07:00<\/CreDtTm><NbOfTxs>3<\/NbOfTxs><CtrlSum>0.20<\/CtrlSum><InitgPty><Nm>ABC Corporation<\/Nm><PstlAdr><StrtNm>Times Square<\/StrtNm><BldgNb>7<\/BldgNb><PstCd>NY 10036<\/PstCd><TwnNm>New .... <\/Document>",
    "date_scheduled" : "2018-07-30",
    "webhooks" : {
        "pain001": "https://credenA:credenB@app.server.com/listener",
    },
    "version" : {
        "initiation" : "001.003",
        "report" : "001.003",
    },
    "status" : "READY",
    "amount" : 50.00,
    "fee" : 8.00,
    "sharing" : "https://dp.link/u/2/ISO145123G6YY",
    "progress" : {
        "count" : 0,
        "of" : 15,
    }
}

GET Create a new PAIN 001 job

Retrieve a PAIN 001 job¶

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/bank/iso20022/v1/pain/001/ISO145123G6YY
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'

URL Parameters

id: ISO145123G6YY - Unique ID of the job

Response 200

Response 200¶

{
    "id" : "ISO145123G6YY",
    "date_creation" : "2016-07-16T19:20:30+01:00",
    "date_last_modified" : "2016-07-16T19:20:30+01:00",
    "description" : "monthly payments",
    "initiation" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn><GrpHdr><MsgId>ABC/090928/CCT001<\/MsgId><CreDtTm>2009-09-28T14:07:00<\/CreDtTm><NbOfTxs>3<\/NbOfTxs><CtrlSum>0.20<\/CtrlSum><InitgPty><Nm>ABC Corporation<\/Nm><PstlAdr><StrtNm>Times Square<\/StrtNm><BldgNb>7<\/BldgNb><PstCd>NY 10036<\/PstCd><TwnNm>New .... <\/Document>",
    "date_scheduled" : "2018-07-30",
    "webhooks" : {
        "pain001": "https://credenA:credenB@app.server.com/listener",
    },
    "version" : {
        "initiation" : "001.003",
        "report" : "001.003",
    },
    "status" : "RUNNING",
    "amount" : 50.00,
    "fee" : 8.00,
    "sharing" : "https://dp.link/u/2/ISO145123G6YY",
    "progress" : {
        "count" : 6,
        "of" : 15
    }
}

DELETE Create a new PAIN 001 job

Delete a PAIN 001 job¶

Delete method changes semanthic depending upon origin status, so :

if origin status is DRAFT or SCHEDULED delete moves order to DELETED
if origin status is RUNNING delete moves order to CANCELLED
if origin status is DONE, delete returns a 409:103 HTTP Status Error

Example¶

Request¶

curl --request DELETE
--url https://api.drop-pay.io/bank/iso20022/v1/pain/001/ISO145123G6YY
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'

URL Parameters

id: ISO145123G6YY - Unique ID of the job

Response 200

Response 200¶

{
    "id" : "ISO145123G6YY",
    "date_creation" : "2016-07-16T19:20:30+01:00",
    "date_last_modified" : "2016-07-16T19:20:30+01:00",
    "description" : "monthly payments",
    "initiation" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn><GrpHdr><MsgId>ABC/090928/CCT001<\/MsgId><CreDtTm>2009-09-28T14:07:00<\/CreDtTm><NbOfTxs>3<\/NbOfTxs><CtrlSum>0.20<\/CtrlSum><InitgPty><Nm>ABC Corporation<\/Nm><PstlAdr><StrtNm>Times Square<\/StrtNm><BldgNb>7<\/BldgNb><PstCd>NY 10036<\/PstCd><TwnNm>New .... <\/Document>",
    "date_scheduled" : "2018-07-30",
    "webhooks" : {
        "pain001": "https://credenA:credenB@app.server.com/listener",
    },
    "version" : {
        "initiation" : "001.003",
        "report" : "001.003",
    },
    "status" : "CANCELLED",
    "amount" : 50.00,
    "fee" : 8.00,
    "sharing" : "https://dp.link/u/2/ISO145123G6YY",
    "progress" : {
        "count" : 6,
        "of" : 15,
    }
}

GET Listing Payment Jobs

Listing Payment Jobs¶

Example¶

Request¶

curl --request GET
--url https://api.drop-pay.io/bank/iso20022/v1/pain/001s{?iban,status,description,date_from,date_to,pg_size,pg_offset}]
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'

URL Parameters

iban: IT63B3606400003351234567 - IBAN of connected account
status: RUNNING, DONE Comma Separated list of Values (CSV) with available status labels.
description: monthly payments text search in job's description property
date_from: 1997-07-16T19:20:30+01:00 (string, optional)
date_to: 1997-07-16T19:20:30+01:00 (string, optional)
pg_size: 100 (number)

Response 200

##### :arrow_down: Response ==200==
``` json
{
     "pain001s": [
         {},
         {},
         {}
     ],
     "paging_info": {
        "current_page": 0,
        "total_pages": 1,
        "page_size": 100,
        "total_items": 3,
        "items_offset": 1
    }
}
```

Group Webhooks & Events¶

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 Authorization json payload
pain001: an URL you provide that is enabled to receive a POST with the updated Authorization json payload

Add a webhook property as show below.

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

Port 443 allowed only (HTTPS)

Please remember that only secure HTTPS on well-known port 443 webhooks are allowed DropPay doesn't validate webhooks URL, but you won't receive any notification event.

Events of useful status updates¶

Event fired when a pain.001 job is started.

{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype": "iso20022.pain001.started",
    "edata": { A PAIN001 entity }
}

Event fired when a pain.001 job has completed its work.

{
    "etime": "2017-06-30T12:00:00+01:00",
    "etype": "iso20022.pain001.completed",
    "edata": { A PAIN001 entity }
}

Webhook	Event
pain001, all	iso20022.pain001.started
pain001, all	iso20022.pain001.completed

DropPay API - Bank v.1 - ISO 20022 Messages - Customer Credit Transfer Initiation (PAIN.001)¶

How it works¶

PAIN 001 and PAIN 002 DropPay specification¶

Unique Message ID¶

Payment Information Blocks¶

Payment Information: Requested Execution Date¶

PAIN 001 Versioning¶

REST Entities¶

PAIN 001.001¶

REST Endpoints¶

Security¶

Manage PAIN 001 jobs¶

Create a new PAIN 001 job¶

The READY status¶

Example¶

Request¶

Response 200¶

Response 200¶

Update a PAIN 001 job¶

Example¶

Request¶

Response 200¶

Retrieve a PAIN 001 job¶

Example¶

Request¶

Response 200¶

Delete a PAIN 001 job¶

Example¶

Request¶

Response 200¶

Listing Payment Jobs¶

Example¶

Request¶

Group Webhooks & Events¶

Webhooks & Events¶

Events of useful status updates¶

The `READY` status¶