Overview

The endpoint is used for initiating a agency or correspondent banking payment. The tables below describes each parameter and provides examples.

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
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
requestedExecutionDate	Mandatory	YYYY-MM-DD	The date on which you want your payment to be processed	2021-12-05
debtorAccount
account	Mandatory	IBAN or account number	Account number issued by you, which will be sent to the creditor as the debtor account	IE29AIBK93115212345678
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
country	Mandatory if Debtor Account is not an IBAN. Optional otherwise	ISO Country Code	Country of financial institution, where debtorAccount resides	IE

debtorName	Mandatory if ultimateDebtorName is not provided. Optional otherwise	Maximum length: 35 Allowed characters* Illegal characters**	Legal name of debtor	Debtor Name
debtorAddress
debtorCountry	Optional	Country representation Format: Alpha 2 ISO 3166-1	Country code of the debtor	DE
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
line2	Optional	Maximum length: 35 Allowed characters* Illegal characters**	Line 2 detailing the address of the debtor	Address line 2
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

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
ultimateDebtorAddress
ultimateDebtorCountry	Optional	Country representation Format: Alpha 2 ISO 3166-1	Country code of the ultimate debtor	DE
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
line2	Optional	Maximum length: 35 Allowed characters* Illegal characters**	Line 2 detailing the address of the ultimate debtor address	Address line 2
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

debtorAgentFinancialInstitution	Mandatory	Bank Identifier Code (BIC)	Your BIC	ABCDIEXXXXX
debtorAgentAccount	Mandatory	IBAN	Your account, within BC Connect, used for settlement of the payment (your Nostro account)	DK1111111111111111
currencyOfTransfer	optional	Format of Alpha 3 ISO 4217	credit currency (if different from debit currency). Applicable when multi-currency payment is intended.	GBP
amount
currency	Mandatory	Format of Alpha 3 ISO 4217	Currency of the amount. Only supported currencies allowed	EUR
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

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
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
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
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
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

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
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
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
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

creditorName	Mandatory if payment targets institutions other than us	Maximum length: 35. Allowed characters. Illegal characters*	Legal name of creditor	Beneficiary name
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
line2	Optional	Maximum length: 35. Allowed characters. Illegal characters*	Line 2 detailing the address of the Creditor	Address line 2
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

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
purposeCode	Conditional	For CNH payments going to China: “GOD”, “STR”, “CTF” or “OTF” For Wero Refunds: "REFU" or "IPRT"	Purpose code is mandatory for CNH payments going to China or for Wero Refunds	GOD
categoryPurposeCode	Conditional	"EPI"	Category purpose code is mandatory for Wero Refunds	EPI
fxQuoteID	Optional		Use the pre-fectched FX quote from Get an FX Quote endpoint.

*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.