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.