Skip to content

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:

  • 1️⃣ 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;
  • 2️⃣ PATCH the job resource until you think it's ready to be launched;
  • 3️⃣ 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.

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

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 requestin 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
1
2
3
4
curl --request POST
--url https://api.drop-pay.io/bank/iso20022/v1/pain/001/
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'
1
2
3
4
5
6
7
8
{
    "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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "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
 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
{
    "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
1
2
3
4
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
1
2
3
{
    "status" : "READY"
}
Response 200
⬇️ 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
{
    "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
1
2
3
4
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "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
1
2
3
4
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "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
1
2
3
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
##### :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.

1
2
3
    "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.

1
2
3
4
5
{
    "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.

1
2
3
4
5
{
    "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