Customer Credit Transfers (Pain.001 / Pain.002)

Banking Circle supports payment initiation and status reporting using the ISO 20022 pain.001 and pain.002 message formats.

ISO 20022 Versions

Banking Circle currently supports the following ISO 20022 message versions for payment initiation and status reporting:

Message Type	Version	Description
`pain.001`	`pain.001.001.03`	Customer Credit Transfer Initiation V3 – Sent by the initiating party to the forwarding or debtor agent to request the movement of funds from the debtor to the creditor.
`pain.002`	`pain.002.001.03`	Customer Payment Status Report V3 – Sent by the instructed agent to the previous party in the payment chain to report the positive, negative, or pending status of a payment instruction (individual or bulk).

All references to pain.001 and pain.002 in this documentation refer to these specific versions unless otherwise stated.

Initiating Payments with `pain.001`

Payment Initiation (`pain.001`)

The pain.001 message is used to initiate credit transfers from a customer to a financial institution. It is submitted in XML format and follows the ISO 20022 standard. You can submit payment initiation requests and receive corresponding status reports via the following API endpoints:

Submit payment initiation (pain.001):
POST /api/v1/payments/iso20022/customer-credit-transfer-initiation

We support both:

Standard credit transfers, and
Payments on behalf of another party (referred to as the Dynamic Sender Name solution)

Note: Payments to Virtual IBANs (VIBANs) are not supported via pain.001 at this time.

Payment Status Report (`pain.002`)

The pain.002 message is used to provide status updates in response to a submitted pain.001 instruction. It delivers structured feedback on the processing outcome, such as acceptance, rejection, or pending status, for each transaction in the batch.

The required content headers and message bodies for both the request and response are described below.

Message Structure & Field Interpretation

For a detailed breakdown of how Banking Circle interprets the fields in the pain.001 message, refer to the following guide:

📄 ISO 20022 Message Implementation Guide

Request Format

Request Headers

Below are the required headers for the request:

Header Name	Required	Format	Description
Accept-Response	Mandatory	String	The response format requested. For payment status reports, use `pain.002.001.03`.
Authorization	Mandatory	String	Bearer token for authentication. Example: `Bearer eyJ0eXAiOiJKV1Q...`
Host	Mandatory	String	Target host. For test environment: `sandbox.bankingcircleconnect.com`. For production: `bankingcircleconnect.com`.
Accept	Mandatory	String	Specifies the acceptable response media types. Valid values: `/`, `application/*`, `application/xml`.
Content-Type	Mandatory	String	The media type of the request body. For example: `multipart/form-data; boundary=---xyz`.
X-Content-Type	Optional	String	This header is not required currently but may become mandatory in future versions. Clients are encouraged to set it to `text/pain001`.
Content-Length	Mandatory	Number	The size of the message body in bytes. For example: `2277`.
Idempotency-Key	Optional	String	A unique value for retry identification. This is useful for retrying the same request without causing duplicate transactions. Max length: 100 characters (if exceeded, the API will return a `400 - Bad Request` error). Example: `2b7b05ad-4411-4a19-8c95-2508b17e0fd8`.

Request Body

The body of the request should contain the pain.001 XML file. Below is the specification:

Parameter	Required	Allowed Input	Description
painFile	Mandatory	UTF-8 file	The XML file containing the `pain.001` message for payment initiation. This is the primary input for the payment request.

Response Format

For every initiated pain.001 XML message, we respond with a pain.002 XML message or an error response. The Customer Payment Status Report (pain.002) provides the status of the initiated credit transfer and gives information about the success or failure of the payment.

Banking Circle API performs a combination of API, XSD, and upfront validations before returning the response. Below are the possible response codes and their descriptions:

Success Responses

Response Code	Content-Type	Description
200 OK	`application/xml`	The request was received and validated, but all payments were rejected and not sent for execution. A `pain.002` status report is generated.
201 Created	`application/xml`	The request was received, validated, and the payments were accepted for processing. A `pain.002` status report is generated.

Note: Both 200 and 201 responses will include the following headers:

Content-Length: Indicates the length of the response body in bytes.
X-Correlation-ID: A GUID used to trace and correlate HTTP requests between client and server.
Request-Context: Used for cross-component correlation, particularly when two of your applications use distinct instrumentation keys.

Error Responses

Response Code	Content-Type	Description
400 Bad Request	`application/json`	The request is not correctly formulated. A `pain.002` is not generated.
403 Forbidden	`application/json`	The server understood the request, but the access is not allowed (e.g., insufficient permissions). No `pain.002` is generated.
404 Not Found	`application/json`	The requested resource (e.g. account) does not exist or the user does not have permission to access it. A `pain.002` is not generated.

Error response examples:

400 – Bad Request (Invalid Structure)

This response is triggered when the header, query or body is not correctly formatted.

{
 "Id": "f7004420-0780-4ed3-ba25-56ed8920a921",
 "Type": "Pain001",
 "Errors": [
   { "ErrorCode": "InvalidFile",
   }
 ]
}

400 – Bad Request (XSD Validation Failure)

This response is triggered when the request is processed successfully, but the XSD validation fails.

{
 "Id": "f7004420-0780-4ed3-ba25-56ed8920a921",
 "Type": "Pain001",
 "Errors": [
   {"ErrorCode": "InvalidFile",
    "ErrorDescription": "The element 'PmtInf' in namespace 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.03' has invalid child element 'PmtInfIdx' in namespace 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.03'. List of possible elements expected: 'PmtInfId' in namespace 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.03'"
   }
 ]
}

404 – Not Found

Returned when the requested resource does not exist or the user does not have permission to access it for example, attempting to retrieve data for a non-existent or unauthorized account.

{
 "errors": [
   {
     "httpStatus": 404,
     "errorCode": null,
     "keyOrMessage": "Not Found",
     "interpolations": [],
     "details": null,
     "exception": null
   }
 ],
  "account": null,
  "_links": null
}