FI-to-FI Credit Transfers (Pacs.008)

Banking Circle supports interbank payment initiation and status reporting using the ISO 20022 pacs.008 and pacs.002 message formats.

ISO 20022 Versions

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

Note: For detailed field definitions and schema reference, see the official SWIFT standards page for pacs.008.001.08.

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

Initiating Payments with pacs.008

Interbank Payment Instruction (pacs.008)

The pacs.008 message is used to instruct a financial institution to transfer funds to another financial institution on behalf of a customer.

It is submitted in XML format and adheres to the ISO 20022 standard for interbank credit transfers. You can initiate payments and receive corresponding status updates via the following API endpoint:

• Submit payment initiation (pacs.008):
  POST /api/v1/payments/iso20022/fi-to-fi-customer-credit-transfer

The pacs.008 endpoint currently only supports initiating Agency Banking and Correspondent Banking payments.

Payment Status Report (pacs.002)

The pacs.002 message is used to deliver status updates for a previously submitted pacs.008 payment instruction. It provides structured information regarding the transaction’s processing outcome, such as acceptance, rejection, or pending, for each message or transaction.

The required content headers and message structures for both the request and response are detailed in the subsequent sections.

Message Structure & Field Interpretation

To successfully initiate a payment, the file submitted should fulfill the following conditions:

• Adhere to the pacs.008 standard
• Only be used for Agency Banking or Correspondent Banking payments
• Meet the message field requirements listed below

Requirements

Optional tags

FX

FX payments are not supported at this time.

Currently, the Interbank Settlement Amount and Currency are copied into both the Transfer Currency and Amount Currency fields.

This is equivalent to initiating a payment without specifying a transfer currency.

Additional tags

Any additional tag included in the file that isn't mandatory according to the Swift pacs.008 standard and listed in the above sections will be ignored.

Request Format

Request Headers

Below are the required headers for the request:

Request Body

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

Response Format

For every initiated pacs.008 XML message, we respond with a pacs.002 XML message or an error response. The FI to FI Payment Status Report (pacs.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

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

Error response examples:

400 – Bad Request (Invalid Structure)

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

{
    "Id": "175e13af-f084-4c3c-a039-9df2df790893",
    "Type": "Pacs008",
    "Errors": [
        {
            "ErrorCode": "InvalidRequest",
            "ErrorDescription": "Unknow error occurred. The Accept-Response header is missing. Please specify one of the supported versions: 'pacs.002.001.10'"
        }
    ]
}

400 – Bad Request (XSD Validation Failure)

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

{
  "Id": "d2404f75-e011-4683-9d2d-efd30943c6b8",
  "Type": "Pacs008",
  "Errors": [
    {
      "ErrorCode": "InvalidFile",
      "ErrorDescription": "The element 'PmtId' in namespace 'urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08' has invalid child element 'TxId' in namespace 'urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08'. List of possible elements expected: 'EndToEndId' in namespace 'urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08'."
    }
  ]
}

400 – Bad Request (Duplicate File)

This response is triggered when the submitted file has already been processed and is rejected to prevent duplication.

{
  "Id": "d2404f75-e011-4683-9d2d-efd30943c6b8",
  "Type": "Pacs008",
  "Errors": [
    {
      "ErrorCode": "DuplicateFileUpload",
      "ErrorDescription": "The file with the same content has been already uploaded. Change the content of the file and upload it again."
    }
  ]
}

400 – Bad Request (Unsupported Accept-Response Version)

Returned when the Accept-Response header includes a version that is not supported by the API.

{
  "Id": "d2404f75-e011-4683-9d2d-efd30943c6b8",
  "Type": "Pacs008",
  "Errors": [
    {
      "ErrorCode": "UnsupportedAcceptResponseVersion",
      "ErrorDescription": "The response version requested in the Accept-Response header is currently not supported. Supported versions are: pacs.002.001.10"
    }
  ]
}

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
}

409 – Conflict (Duplicate Idempotency Key)

This response is triggered when the Idempotency-Key has already been used in a previous request. The server prevents duplicate processing.

{
  "Id": "d2404f75-e011-4683-9d2d-efd30943c6b8",
  "Type": "Pacs008",
  "Errors": [
    {
      "PaymentBulkId": "fa5eba78-a2a5-4ceb-916a-d3fd355c94cb",
      "ErrorCode": "DuplicateIdempotencyKey",
      "ErrorDescription": "Identical Idempotency Key is already uploaded once for this user."
    }
  ]
}