API Reference
Client PortalAPI StatusWebsite

Credit transfer instruction endpoint.

post
https://www.bankingcircleconnect.com/api/v1/payments/credit-transfer-instructions

Credit transfer instruction endpoint.

This is a unified interface for submitting Credit Transfer Instructions. It consolidates and is intended to replace several existing payment endpoints under a single resource, using content-negotiated request and response formats. The endpoints listed in the table below are planned for deprecation and will be supported through this endpoint.

📘

From the start of November 2026, applicable payment schemes will require Town Name and Country Code in dedicated address fields. Existing address requirements continue to apply.

Legacy EndpointFormatSupported on new unified endpoint
POST /api/v1/payments/iso20022/customer-credit-transfer-initiation [DEPRECATED]PAIN.001.001.03 (XML)Yes - Upgrade to PAIN.001.001.09 required
POST /api/v1/payments/iso20022/fi-to-fi-customer-credit-transferPACS.008.001.08 (XML)Future planned
POST /api/v1/payments/fi-to-fi-customer-credit-transfer-initiationJSONFuture planned
POST /api/v1/payments/bulksCSVFuture planned
POST /api/v1/payments/singlesJSONFuture planned

Currently supported formats

Request FormatContent-TypeAcceptResponse Format
PAIN.001.001.09 (XML file)multipart/form-data*/*PAIN.002.001.10 (application/xml)
❗️

PAIN.001.001.03 is not supported via this endpoint. Integrations currently using the deprecated /api/v1/payments/iso20022/customer-credit-transfer-initiation endpoint must additionally upgrade to PAIN.001.001.09 to migrate to this endpoint.

See PAIN.001.001.03 to PAIN.001.001.09 Migration Guide for further instructions.

Content negotiation

The endpoint uses standard HTTP content negotiation to determine the request format and select the appropriate response format. As new formats are added (JSON, CSV, etc.), the Content-Type and Accept headers will be the mechanism by which the client selects the desired behavior — the URL stays the same.

ISO 20022 Formats

For ISO 20022 formats (e.g. PAIN, PACS), the payload must be provided as a file using multipart/form-data as the Content-Type. The message format is determined based on the namespace tag in the file.

HTTP Request Headers

HeaderRequiredDescription
Content-TypeYesUsed to describe the format provided.
AcceptNoDesired response format. Defaults to deriving the response format from the request format.
Idempotency-KeyNoA unique key to ensure idempotent processing More info
TruncateNoSet to true to allow us to truncate fields that exceed internal length limits (instead of validation failure). It is however recommended that clients truncate on their side to avoid unexpected data loss. See section Truncation section below for more details.

HTTP Status Codes

StatusMeaningResponse Format
201 CreatedAll credit transfer instructions accepted and sent for processing.Depends on request format (i.e. PAIN.002 for PAIN.001 request format)
400 Bad RequestMalformed request (e.g. invalid XML / JSON).JSON
406 Not AcceptableThe Accept header does not match a supported response format for this request type.JSON
409 ConflictIdempotency-key violation (duplicate submission).JSON
415 Unsupported Media TypeThe Content-Type is not supported.—
422 Unprocessable EntityRequest was parsed but one or more credit transfer instructions failed validation. No credit transfer instructions was sent for processing.Depends on request format (i.e. PAIN.002 for PAIN.001 request format)
500 Internal Server ErrorAn unexpected server fault occurred—
❗️

Note: 400 Bad Request was formerly used for a range of different errors including validation errors. If a request has validation errors the response code will instead be a 422 indicating that request was understood but failed validation.

📘

Note: Partial processing is not supported. 201 Created means all credit transfer instructions was accepted and sent for processing. Any other response code means that no credit transfer instructions was sent for processing.

Fields

Truncation

📘

On some legacy endpoints, field content exceeding length limits was truncated on the Banking Circle side. This behaviour no longer applies unless explicitly enabled via the Truncate header.

When the header is set to true, fields exceeding internal length limits are truncated instead of causing a validation failure. It is recommended to perform truncation prior to submission to avoid unexpected data loss.

The truncation functionality is only supported on fields where we have a length limitation that is stricter than the official ISO 20022 limitation. Look for "Opt-In Truncation Supported" in field description table below.

Descriptions

The table below describes the instruction fields across formats (currently only PAIN.001.001.09). The limits such as max length, allowed characters etc. and whether they are mandatory or not are based on Banking Circle requirements. It may be that a field is listed as optional though it may be required by a certain ISO 20022 format etc.

📘

Some fields has a requirement it terms of allowed characters. Fields marked with Allowed characters only must begin with an alphanumeric character or one of / ,?, (, ) , ., ,, _, ', +. Subsequent characters may additionally include - and : . All other characters are rejected.


NamePAIN.001.001.09 (Document/CstmrCdtTrfInitn)Description
MessageReferenceGrpHdr/MsgIdUnique message identifier.

  • Optional

  • Max length: 128

  • Allowed characters only

RequestedExecutionDatePmtInf/ReqdExctnDt/DRequested execution date.

  • Mandatory

  • ISO 8601: yyyy-MM-dd

DebtorPmtInf/DbtrDebtor (payer).
See the Party Identification block.

  • Mandatory for Dynamic Sender Name and Agency Banking.

DebtorAccountPmtInf/DbtrAcct/Id/IBAN
OR
Debtor IBAN or account number.

  • Mandatory

  • Max length: 34

PmtInf/DbtrAcct/Id/Othr/Id
InstrIdPmtInf/CdtTrfTxInf[x]/PmtId/InstrIdUnique instruction identification.

  • Optional

  • Max length: 35

  • Allowed characters only

EndToEndIdPmtInf/CdtTrfTxInf[x]/PmtId/EndToEndIdEnd-to-end identification.

  • Optional

  • Max length: 35

  • Allowed characters only

AmountPmtInf/CdtTrfTxInf[x]/Amt/InstdAmt
OR
Amount to be transferred.

  • Mandatory

PmtInf/CdtTrfTxInf[x]/Amt/EqvtAmt/Amt
AmountCurrencyPmtInf/CdtTrfTxInf[x]/Amt/InstdAmt/@Ccy
OR
Amount currency.

  • Mandatory

  • ISO 4217

PmtInf/CdtTrfTxInf[x]/Amt/EqvtAmt/Amt/@Ccy
TransferCurrencyPmtInf/CdtTrfTxInf[x]/Amt/EqvtAmt/CcyOfTrfTarget transfer currency.

  • Optional

  • ISO 4217

ChargeBearerPmtInf/CdtTrfTxInf[x]/ChrgBrCharge bearer.

  • Optional

  • SHAR, DEBT, CRED, SLEV

ServiceLevelPmtInf/CdtTrfTxInf[x]/PmtTpInf/SvcLvl[s]/Cd
OR
Service level.

  • Optional

  • INST, NURG, URGP

PmtInf/CdtTrfTxInf[x]/PmtTpInf/SvcLvl[s]/Prtry
CategoryPurposeCodePmtInf/CdtTrfTxInf[x]/PmtTpInf/CtgyPurp/Cd
OR
Category purpose code.

  • Optional

  • EPI

PmtInf/CdtTrfTxInf[x]/PmtTpInf/CtgyPurp/Prtry
PurposeCodePmtInf/CdtTrfTxInf[x]/Purp/Cd
OR
Payment purpose.

  • Optional

  • REFU,IPRT,PENS,SALA,SUPP,RENT

PmtInf/CdtTrfTxInf[x]/Purp/Prtry

  • GOD,STR,CTF,OTF

ClientCustomerIdPmtInf/CdtTrfTxInf[x]/InstrForDbtrAgtThis is a client internal reference that follows the
ultimate debtor’s name and is used for tracking and reconciliation.

  • Mandatory for Dynamic Sender Name.

  • Max length: 35

  • Allowed characters only

RemittanceInformationPmtInf/CdtTrfTxInf[x]/RmtInf/Ustrd[1]Remittance information.

  • Optional

  • Max length: 140

  • Allowed characters only

CreditorPmtInf/CdtTrfTxInf[x]/CdtrCreditor (beneficiary). See the Party Identification block.

  • Mandatory

CreditorAccountPmtInf/CdtTrfTxInf[x]/CdtrAcct/Id/IBAN
OR
Creditor IBAN or account number.

  • Mandatory

  • Max length: 34

PmtInf/CdtTrfTxInf[x]/CdtrAcct/Id/Othr/Id
CreditorAgentPmtInf/CdtTrfTxInf[x]/CdtrAgt/FinInstnIdCreditor agent (beneficiary bank). See the Financial Institution block.

  • Mandatory if CreditorAccount is not an IBAN

UltimateDebtorPmtInf/CdtTrfTxInf[x]/UltmtDbtrUltimate debtor. See the Party Identification block.

  • Mandatory for Dynamic Sender Name and Agency Banking.

Party Identification block

Used by Debtor, Creditor and Ultimate Debtor. Paths are relative to the party's base path.

NamePAIN.001.001.09Description
NameNmParty name.

  • Mandatory

  • Max length: 35

  • Allowed characters only

  • Opt-In Truncation Supported

PostalAddressPstlAdrPostal address. See the Postal Address block.

  • Mandatory

Postal Address block

Used by the Party Identification block. Paths are relative to the party's PostalAddress.

NamePAIN.001.001.09Description
AddressLine1AdrLine[1]Unstructured address line 1.

  • Mandatory

  • Max length: 35

  • Allowed characters only

  • Opt-In Truncation Supported

AddressLine2AdrLine[2]Unstructured address line 2.

  • Optional

  • Max length: 35

  • Allowed characters only

  • Opt-In Truncation Supported

AddressLine3AdrLine[3]Unstructured address line 3.

  • Optional

  • Max length: 35

  • Allowed characters only

  • Opt-In Truncation Supported

CountryCodeCtryCountry Code.

  • Optional

  • ISO 3166 alpha-2

DepartmentDeptDepartment.

  • Optional

  • Max length: 70

SubDepartmentSubDeptSub-department.

  • Optional

  • Max length: 70

StreetNameStrtNmStreet name.

  • Optional

  • Max length: 70

BuildingNumberBldgNbBuilding number.

  • Optional

  • Max length: 16

BuildingNameBldgNmBuilding name.

  • Optional

  • Max length: 35

FloorFlrFloor.

  • Optional

  • Max length: 70

PostBoxPstBxPost office box.

  • Optional

  • Max length: 16

RoomRoomRoom.

  • Optional

  • Max length: 70

PostalCodePstCdPostal code.

  • Optional

  • Max length: 16

TownNameTwnNmTown or city.

  • Optional

  • Max length: 35

TownLocationNameTwnLctnNmLocation within a town.

  • Optional

  • Max length: 35

DistrictNameDstrctNmDistrict.

  • Optional

  • Max length: 35

CountrySubDivisionCtrySubDvsnCountry sub-division (state/province).

  • Optional

  • Max length: 35

Financial Institution block

Used by Creditor Agent. Paths below are relative to the CreditorAgent property
(PmtInf/CdtTrfTxInf[x]/CdtrAgt/FinInstnId).

NamePAIN.001.001.09Description
BICBICFIFinancial institution BIC.

  • Mandatory if NCC not set

  • Max length: 11

NCCClrSysMmbId/MmbIdNational clearing code.

  • Mandatory if BIC not set

  • Max length: 20

CountryCodeClrSysMmbId/ClrSysId/Cd
OR
Clearing system code (first 2 chars = CountryCode).

  • Mandatory if BIC not set

ClrSysMmbId/ClrSysId/PrtryCountryCode.

Validation Errors

See Error Codes

Headers
string

Unique value generated by the user which the API uses to recognize subsequent retries of the same request.
This field is limited to a maximum of 100 characters, if not upheld the API will return with an error 400 - Bad Request.
Example: 2b7b05ad-4411-4a19-8c95-2508b17e0fd8

string

For internal reasons we have some fields with stricter length requirements compared to the ISO standard. You can "instruct" us to do truncation for these particular fields by setting this header to "true".
It is however recommended that the caller performs truncation on their side to prevent unexpected data loss. The Truncate header is there for callers who for any reason are not able to do so.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated 1 day ago

Language
Credentials
Bearer
LoadingLoading…
Response
Choose an example:
application/xml
application/json
*/*

Updated 1 day ago