Correspondent and Agency Banking
Initiate payments from account numbers issued under your own BIC or National Clearing Code
To send and receive data from the BC Connect API, you must be authenticated and have a valid access token. For more details on how to generate access tokens and authenticate, please see Connect to the API and Authorisation.
You will use the fi-to-fi-customer-credit-transfer-initiation endpoint to instruct Correspondent and Agency Banking payments from your own BIC and IBANs, via us. The endpoint is described in more details here: Agency and Correspondent Banking payments.
You can also read more about the Correspondent Banking solution in general.
The request body format is JSON. The tables below describes each parameter and provides examples. For Correspondent Banking payments, you can also see which field in a MT103, each parameter is carried forward to.
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 |
| 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 |
| debtorAgentFinancialInstitution | Mandatory | Bank Identifier Code (BIC) | Your BIC | ABCDIEXXXXX | 52A |
| debtorAgentAccount | Mandatory | IBAN | Your account, within BC Connect, used for settlement of the payment (your Nostro account) | 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 |
| 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 | “GOD”, “STR”, “CTF” or “OTF” | Purpose code is mandatory for CNH payments going to China | GOD | n/a |
| fxQuoteID | Optional | Use the pre-fectched FX quote from Get an FX Quote endpoint. | 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.
Debtor and ultimate debtor details
In a Correspondent Banking or Agency Banking flow, for outgoing payments, you are seen as the 'ordering institution', and your customer as the 'ordering customer'. However, depending on your agreement with us, you may be initiating payments on behalf of your customer's customer. The Correspondent Banking and Agency Banking payment initiation endpoint caters to both scenarios, by allowing you to provide:
- Debtor name and address
- Ultimate debtor name and address
Either debtor or ultimate debtor must be provided. If both are provided, the ultimate debtor details will be carried forward as the debtor name, as illustrated below:
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.
Payment status, notifications and reports
To check the status of a payment, you can use the Get payments endpoints. You can receive notifications by subscribing to Webhooks. Furthermore, the reconciliation reports enables your reconciliation.
Compared to the other payment solutions, BC Connect supports, the Correspondent and Agency Banking payments contain an additional layer of information about the account, which you have issued to your customer, under your own BIC or National Clearing Code.
Across the Get payments and reports endpoints, we generally refer to these as the ultimateDebtorAccountor the ultimateCreditorAccount, depending on the direction of the payment.
In the table below, you will find an overview of the most common account, debtor and creditor details, and where to find those details in the reconciliation reports and the Get payments endpoints.
| Payment details | Property in GET payments endpoints and notifications | Property in the reconciliation report |
|---|---|---|
| Debtor’s financial institution | Incoming payment: debtorInformation.account.financialInstitution Outgoing payment: debtorAccount.financialInstitution | debtoragentBankCode |
| Debtor’s account number | Incoming payment: debtorAccount Outgoing payment: ultimateDebtorAccount | Incoming payment: debtorAccount Outgoing payment: ultimatedebtorAccount |
| Debtor’s name | debtorName | Incoming payment: debtorLine1 Outgoing payment: ultimatedebtorLine1 |
| Debtor’s address | Incoming payment: debtorAddress Outgoing payment: ultimateDebtorAddress | Incoming payment: debtorLine3-4 Outgoing payment: ultimatedebtorLine2-4 |
| Creditor’s financial institution | creditorInformation.account.financialInstitution | beneficiaryBankCode |
| Creditor’s account number | Incoming payment: ultimateCreditorAccount Outgoing payment: creditorAccount | Incoming payment: ultimatebeneficiaryAccount Outgoing payment: beneficiaryAccount |
| Creditor’s name | creditorName | beneficiaryLine1 |
| Creditor’s address | creditorAddress | beneficiaryLine2-4 |
| Your settlement (Nostro) account with us | Incoming payment: creditorInformation.account Outgoing payment: debtorAccount.account | Incoming payment: account or beneficiaryAccount Outgoing payment: account or debtorAccount |
Sending Payment with FX
Correspondent Banking solution allows you to send and receive payments in up to 24 currencies with a single currency nostro account of your choice.
Instruct outbound payments with a live rate or using a quote obtained via our Request for Quote (RFQ) solution.
BC Connect’s Correspondent Banking with FX solution for payments combines our Correspondent Banking and FX capabilities in one of the two following ways:
A. Embedded currency conversion for instruction via API by populating currencyOfTransfer, once a different currency is specified here than in amount, the system knows an embedded FX transaction will be triggered.
B. Obtain the quote prior to payment initiation via RFQ, which locks the rate for 30 seconds. Include the QuoteID obtained in your payment instruction in fxQuoteID.
Updated 17 days ago