post
https://www.bankingcircleconnect.com/api/v1/payments/fi-to-fi-customer-credit-transfer-initiation
Overview
The endpoint is used for initiating a agency or correspondent banking payment. The tables below describes each parameter and provides examples.
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.
Duplicate check using idempotency key
We have enhanced our duplicate checks by extending all payment initiation endpoints to accept an idempotency key header. The key can prevent the same payment from getting initiated more than once, for example in case of connectivity issues. The idempotency key, provided by you, needs to be unique and maximum 100 characters. The key will be valid for 10 days.
If the idempotency key is more than 100 characters, the endpoint will return a "400 Bad Request".
If the idempotency key is not unique (if the key has been used for the initiation of a previous payment within the past 10 days), the endpoint will return a "409 Conflict" and return the paymentId of the payment, for which the idempotency key was previously used.
This key will not be exposed in any report or endpoint.
Content specification
Content specifications header
| Parameter | Required | Allowed input | Description | Example |
|---|---|---|---|---|
| X-MessageReference | Optional | String | Unique reference of the HTTP request. If left blank this field will be populated with a GUID | 6198eb60-d1dd-4aad-9bbd-b01a49214e62 |
| Idempotency-Key | Optional | 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 | 2b7b05ad-4411-4a19-8c95-2508b17e0fd8 |
Content specifications body
| Parameter | Required | Allowed input | Description | Example | MT103 fields |
|---|---|---|---|---|---|
| instrId | Optional | Maximum length: 35 Allowed characters* Illegal characters** | Reference, which can be used for your own reconciliation. Available in the reconciliation and rejection reports under the property called UserReferenceNumber. This field is not included in the payment details sent to the creditor. | ABCDEFGHIJKL | 20 |
| requestedExecutionDate | Mandatory | YYYY-MM-DD | The date on which you want your payment to be processed | 2021-12-05 | 32A |
| debtorAccount | |||||
| account | Mandatory | IBAN or account number | Account number issued by you, which will be sent to the creditor as the debtor account | IE29AIBK93115212345678 | 50K |
| financialInstitution | Mandatory if Debtor Account is not an IBAN. Optional otherwise | Bank Identifier Code (BIC) or a National Clearing Code (NCC) | Financial Institution where debtorAccount resides | ABCDIEXXXXX or SC083002 | 52A |
| country | Mandatory if Debtor Account is not an IBAN. Optional otherwise | ISO Country Code | Country of financial institution, where debtorAccount resides | IE | n/a |
| debtorName | Mandatory if ultimateDebtorName is not provided. Optional otherwise | Maximum length: 35 Allowed characters* Illegal characters** | Legal name of debtor | Debtor Name | 50K |
| debtorAddress | |||||
| line1 | Mandatory if ultimateDebtorAddressLine1 is not provided. Optional otherwise | Maximum length: 35 Allowed characters* Illegal characters** | Line 1 detailing the address of the debtor | Address line 1 | 50K |
| line2 | Optional | Maximum length: 35 Allowed characters* Illegal characters** | Line 2 detailing the address of the debtor | Address line 2 | 50K |
| line3 | Optional | Maximum length: 35 Allowed characters* Illegal characters** | Line 3 detailing the address of the debtor 3rd address line also referred to as “city field”. Fill with Country as Alpha 2 ISO 3166-1 and city name with postal code | IE – Dublin, D02 RF29 | 50K |
| debtorCountry | Mandatory unless provided under the Ultimate Debtor country. | Country representation Format: Alpha 2 ISO 3166-1 | Country code of the debtor | DE | 50K |
| (coming soon) debtorTown | Mandatory unless provided under the corresponding Ultimate Debtor town. | Maximum length: 35 | Town name of the debtor | Berlin | |
| ultimateDebtorName | Mandatory if debtorName is not provided Optional elsewise If populated, it will be carried forward as the debtor name | Maximum length: 35 Allowed characters* Illegal characters** | Legal name of ultimate debtor | Ultimate debtor name | 50K |
| ultimateDebtorAddress | |||||
| line1 | Mandatory if debtorAddressLine1 is not provided Optional elsewise If populated, it will be carried forward as the debtor address | Maximum length: 35 Allowed characters* Illegal characters** | Line 1 detailing the address of the ultimate debtor address | Address line 1 | 50K |
| line2 | Optional | Maximum length: 35 Allowed characters* Illegal characters** | Line 2 detailing the address of the ultimate debtor address | Address line 2 | 50K |
| line3 | Optional | Maximum length: 35 Allowed characters* Illegal characters** | Line 3 detailing the address of the ultimate debtor address 3rd address line also referred to as city field. Fill with Country as Alpha 2 ISO 3166-1 and city name with postal code | IE – Dublin, D02 RF29 | 50K |
| ultimateDebtorCountry | Mandatory unless provided under the corresponding Debtor country. | Country representation Format: Alpha 2 ISO 3166-1 | Country code of the ultimate debtor | IE | 50K |
| (coming soon) ultimateDebtorTown | Mandatory unless provided under the corresponding Ultimate Debtor town. | Maximum length: 35 | Town of the ultimate debtor | Dublin | |
| debtorAgentFinancialInstitution | Mandatory | Bank Identifier Code (BIC) | Your BIC | ABCDIEXXXXX | 52A |
| debtorAgentAccount | Mandatory | IBAN or account number | Your account, within BC Connect, used for settlement of the payment (your Nostro account) Account number can be provided for branches not supporting IBANs | DK1111111111111111 | 53B |
| currencyOfTransfer | optional | Format of Alpha 3 ISO 4217 | credit currency (if different from debit currency). Applicable when multi-currency payment is intended. | GBP | 32A |
| amount | |||||
| currency | Mandatory | Format of Alpha 3 ISO 4217 | Currency of the amount. Only supported currencies allowed | EUR | 32A, 33B |
| amount | Mandatory | Must be larger than zero and formatted without the one thousand separator using a full stop ‘.’ as the decimal separator. Must conform with allowed number of decimals for selected Amount Currency | Instructed amount | Valid examples (GBP): 100 or 100. or 100.00. Invalid examples (GBP): 1,100 or 1,100.00 or 1100.000 | 32A, 33B |
| chargeBearer | Mandatory | "SHA", "OUR" or "BEN" | Determines which of the parties will be charged the payment fee. We will either carry the instructed charge bearer value forward, or overwrite the value, before executing the payment. This depends on the client’s “charge bearer setup”, and the payment rail used to execute the payment. | SHA | 71A |
| remittanceInformation | |||||
| line1 | Optional | Maximum length: 35. Allowed characters . Illegal characters Truncation | Line 1 of the textual information passed from Debtor to Creditor as part of the transfer | Free text field | 70 |
| line2 | Optional | Maximum length: 35. Allowed characters*. Illegal characters** | Line 2 of the textual information passed from Debtor to Creditor as part of the transfer | Free text field | 70 |
| line3 | Optional | Maximum length: 35. Allowed characters*. Illegal characters** | Line 3 of the textual information passed from Debtor to Creditor as part of the transfer | Free text field | 70 |
| line4 | Optional | Maximum length: 35 Allowed characters* Illegal characters** | Line 4 of the textual information passed from Debtor to Creditor as part of the transfer | Free text field | 70 |
| CreditorId | Mandatory if creditorAccount is left blank | GUID | ID of the creditor if they are created as a pre-defined beneficiary | 3d7279c9-bca2-444f-a872-a8dc042f1c63 | n/a |
| creditorAccount | |||||
| account | Mandatory, unless CreditorId is populated | IBAN or account number | Account of the creditor that will receive funds. Can be either an account number or an International Bank Account Number (IBAN). | DK5989000000054321 | 59 |
| financialInstitution | Mandatory if Creditor Account is not an IBAN and CreditorId is not populated. Optional otherwise | Can be either a Bank Identifier Code (BIC) or a National Clearing Code.Supported National Clearing Codes:UK – Sort Code requires prefix with ‘SC’ followed by the 6-digit sort code.US – Fedwire Code requires prefix with ‘FW’ followed by 9-digit Fedwire/ABA | Financial Institution where Creditor Account resides | WIREDEMM or SC123456 | 57A |
| country | Mandatory if Creditor Account is not an IBAN and CreditorId is not populated. Optional otherwise | ISO Country Code | Country of receiver’s bank | DE | n/a |
| creditorName | Mandatory if payment targets institutions other than us | Maximum length: 35. Allowed characters*. Illegal characters** | Legal name of creditor | Beneficiary name | 59 |
| creditorAddress | |||||
| line1 | Mandatory if payment targets institutions other than us. Optional otherwise | Maximum length: 35. Allowed characters*. Illegal characters** | Line 1 detailing the address of the Creditor | Address line 1 | 59 |
| line2 | Optional | Maximum length: 35. Allowed characters*. Illegal characters** | Line 2 detailing the address of the Creditor | Address line 2 | 59 |
| line3 | Optional | Maximum length: 35. Allowed characters*. Illegal characters** | Line 3 detailing the address of the Creditor. 3rd address line also referred to as city field. Fill with Country as Alpha 2 ISO 3166-1 and city name with postal code | DE – 10117 Berlin | 59 |
| (coming soon) creditorCountry | Mandatory | Country representation Format: Alpha 2 ISO 3166-1 | Country code of the creditor | DE | |
| (coming soon) creditorTown | Mandatory | Maximum length: 35. | Town of the creditor | Berlin | |
| clearingNetwork | Optional | Only allowed values: "SEPAINST", "SEPA" or "T2" | Use this parameter to select the payment rail to be used for executing the payment | SEPAINST | n/a |
| purposeCode | Conditional | Purpose code For CNH payments going to China: “GOD”, “STR”, “CTF” or “OTF” For Wero Refunds: | Purpose code is mandatory for CNH payments going to China or for Wero Refunds | GOD | n/a |
| categoryPurposeCode | Conditional | "EPI" | Category purpose code is mandatory for Wero Refunds | EPI | n/a |
| fxQuoteID | Optional | Use the pre-fectched FX quote from Get an FX Quote endpoint. | n/a | ||
| serviceLevels | Optional | Only allowed values: "INST", "NURG", "URGP" | Use this parameter to select the payment rail(s) to be used for executing the payment. You can specify one or more values. | ["INST","URGP"] | n/a |
*Characters allowed:
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . , ' + _
Space**Illegal characters:
- Field only composed of blank characters (space)
- First character is colon (:) or hyphen (-)
***Truncation:
For remittance information, maximum 140 characters allowed collectively from line 1 to line 4. The characters exceeding 140 characters will be discarded.