post
https://www.bankingcircleconnect.com/api/v1/payments/bulks
The endpoint is used to initiate a bulk payment, which allows for multiple payments to be initiated at the same time. Read more about bulk payments here.
The endpoint is used to initiate multiple payments in a single request using a CSV file. Read more about Bulk Payments. The endpoint accepts up to 50,000 payments per file.
The content type for bulk payments is multipart/form-data.
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.
Content specifications header
| Parameter | Required | Allowed input | Description | Example |
|---|---|---|---|---|
| X-Content-type | Optional | text/csvv0 | Specifying content type. Currently supported type is "text/csvv0" | text/csvv0 |
| 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 |
| X-Channel | Optional | channel/api | Channel reference of the payment | channel/api |
| ProceedWithErrors | Optional | true or false | Allow Bulk payment to be partially accepted. Read more about partial bulk processing . Default: false | false |
| 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
For the bulk payments only CSV files are accepted as body content. Optional fields may be left empty, but not skipped. Insert the comma as when you separate populated fields. Each payment should be on its own line. The content and format of the file is specified in the below table.
| Field | Parameter | Required | Allowed input | Description | Example |
|---|---|---|---|---|---|
| 1 | Debtor Customer ID | Mandatory (for technical reasons) | 9-digit Numeric | Customer ID for the debtor account. Field is not utilised, but needs to be populated with a value to ensure that file is read properly | 999999999 |
| 2 | Debtor Account | Mandatory | IBAN | Account from which you want funds debited | DK4789000000012345 |
| 3 | Debtor Account Branch Code | Optional | 10 | The bank branch for the debtor account is always 010 | 10 |
| 4 | Debtor Account Currency | Optional | Alphabetic | The currency for the debtor account populated in field 2 | EUR |
| 5 | Amount | Mandatory | Must be larger than zero. Separators can not be included | Instructed amount | Valid examples (GBP): 100 or 100. or 100.00. Invalid examples (GBP): 1,100 or 1,100.00 or 1100.000 |
| 6 | Currency of Transfer | Mandatory | Alphabetic. Format of Alpha 3 ISO 4217 | Currency of the amount that will be transferred to the creditor | EUR |
| 7 | Requested Execution Date | Mandatory | DDMMYYYY | The date on which you would like your payment to be processed and debited on your Debtor Account. The date must be current date within currency cut off or future Value date | 25012022 |
| 8 | Payment Type | Optional | A | 'A' (for ad-hoc/general payment type) | A |
| 9 | Creditor Name | Mandatory if payment targets institutions other than BC | Maximum length: 35 . Allowed characters*. Illegal characters** | Name of the creditor that will receive funds | Company A |
| 10 | Creditor Account | Mandatory | IBAN or Account no. | Account of the creditor that will receive funds. Can be either an account number or an International Bank Account Number (IBAN) | Examples: IBAN: DK5989000000054321 Account number: 0000054321 |
| 11 | Transfer Mode | Optional | S | 'S' for SWIFT | S |
| 12 | Creditor Account Financial Institution | Conditional: Mandatory if Creditor Account is not an IBAN. Optional otherwise | 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 code. | Financial Institution where Creditor Account reside. Can be either a Bank Identifier Code (BIC) or a National Clearing Code | Example BIC: SXPYDKKKXXX. National clearing codes: SC123456FW123456789 |
| 13 | Beneficiary e-mail | Optional | Email of the beneficiary. The field does not carry additional functionality | [email protected] | |
| 14 | Remittance Information Line 1 | Optional | Maximum length: 35 . Allowed characters*. Illegal characters** | Line 1 of the textual information passed from Debtor to Creditor as part of the transfer. Purpose code required for AED and SAR in this field. | Free text field |
| 15 | Remittance Information Line 2 | 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 |
| 16 | Remittance Information Line 3 | 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 |
| 17 | Remittance Information Line 4 | 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 |
| 18 | Charge Bearer | Mandatory | "SHA", "BEN" or "OUR" | Determines which of the parties will be charged the payment fee. BC Connect 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 |
| 19 | Debtor Narrative to Self | Optional | Maximum length: 35. Allowed characters* | Dual purpose: Internal reference for client OR Virtual International Bank Account Number (VIBAN): the IBAN of one of your VIBANs | Free text field |
| 20 | Narrative for Creditor | Optional | Maximum length: 35. Allowed characters* | Additional narrative. The field has no functional impact and not included in reporting. | Free text field |
| 21 | Amount Currency | Mandatory | Alphabetic | Currency of the Amount Amount Currency must match one of Debtor Account Currency. Example: I would like 100 EUR from my EUR account sent to Creditor Account in GBP (currency of transfer). Currency of transfer. Example: I want to withdraw from my EUR account what is required to pay my invoice of exactly 100 GBP (Currency of transfer) to Creditor Account | GBP |
| 22 | Debtor Reference | Conditional: Mandatory when using the Payment Sender Reference solution, optional otherwise | Maximum length: 35. Allowed characters* | Debtor own reference. Own reference which can be used for own reconciliation. When using the Payment Sender Reference solution: use this field to include your customer's unique identifier. It must be a static ID uniquely linked to each debtor i.e. phone number or account number.' It is used for transaction monitoring of payer payments and behaviour. | Debtor reference from your system |
| 23 | Creditor Address Line 1 | Conditional*** Mandatory if payment targets other institutions than BC | Maximum length: 35. Allowed characters*. Illegal characters** | Line 1 detailing the address of the Creditor. Mandatory: Only for payment targeting other institutions than BC | Free text field |
| 24 | Creditor Address Line 2 | Optional*** | Maximum length: 35. Allowed characters*. Illegal characters** | Line 2 detailing the address of the Creditor | Free text field |
| 25 | Creditor Address Line 3 | Optional*** | Maximum length: 35. Allowed characters*. Illegal characters** | Line 3 detailing the address of the Creditor3rd address line also referred to as city field. Fill with country/city name with postal code. | Examples: DK - 2900 Hellerup or GB - London EC2M 4AY |
| 26 | Intracompany | Optional | N | 'N' can be used | N |
| 27 | Clearing Network | Optional | Only allowed values: "SEPAINST", "SEPA" or "T2" | Use this parameter to select the payment rail to be used for executing the payment | SEPAINST |
| 28 | Purpose Code | Conditional | For CNH payments going to China: “GOD”, “STR”, “CTF”,“OTF” or for Wero Refunds | is mandatory for CNH payments going to China or for Wero Refunds | GOD |
| 29 | Service Level / Prioritized Clearing Networks | Optional | "INST", "NURG", "URGP", "SEPAINST", "SCT", "T2" Can contain one or more values. | Allows you to specify which payment rails to use, in your preferred order. This option overrides our default logic, with no automatic fallback to other networks | “INST,URGP" |
| 30 | Category purpose code | Conditional | "EPI" | Is mandatory for Wero Refunds | EPI |
| 31 | Ultimate Debtor Name | Conditional | Maximum length: 35. Allowed characters*. Illegal characters** | Your customer's name. Required If utilizing Dynamic Sender Name, ignored otherwise. | Company Z |
| 32 | Ultimate Debtor Address Line 1 | Conditional | Maximum length: 35. Allowed characters*. Illegal characters** | Your customer's address. Required If utilizing Dynamic Sender Name, ignored otherwise. | Free text field |
| 33 | Ultimate Debtor Address Line 2 | Optional | Maximum length: 35. Allowed characters*. Illegal characters** | Your customer's state and post code | Example: Bayern, 80802 |
| 34 | Ultimate Debtor Address Line 3 | Conditional | Maximum length: 35. Allowed characters*. Illegal characters** | Your customer's ISO country code. Required If utilizing Dynamic Sender Name, ignored otherwise. | Example: DE |
| 35 | Client Customer Id | Conditional | Maximum length: 35. Allowed characters*. Illegal characters** | Your customer's unique identifier. Required if utilizing Dynamic Sender Name. This field must have a static ID uniquely linked to each debtor for utilization for transaction monitoring of payer payments and behaviour, i.e. phone number or account number. Same as PAIN.001 or PACS.008 tag <InstrForDbtrAgt>. | Free text field |
| 36 | Ultimate Debtor Financial Institution | Conditional | Bank Identifier Code (BIC) or a National Clearing Code (NCC) | BIC or NCC of the financial institution servicing the ultimate debtor. Required If utilizing Dynamic Sender Name, ignored otherwise. | Example: SXPYDKKKXXX or SC083002 |
| 37 | Ultimate Debtor Country Code | Conditional | Country representation Format: Alpha 2 ISO 3166-1 | Country code of the ultimate debtor. Required if utilizing Dynamic Sender Name | DE |
| 38 | (coming soon) UltimateDebtorTown | Conditional | Maximum length: 35. | Town name of the ultimate debtor -Required if utilizing Dynamic Sender Name | Berlin |
| 39 | (coming soon) BeneficiaryCountryCode | Mandatory | Country representation Format: Alpha 2 ISO 3166-1 | Country code of the beneficiary | DE |
| 40 | (coming soon) BeneficiaryTown | Mandatory | Maximum length: 35. | Town name of the beneficiary | Berlin |
After initiating a payment
Upon successfully sending a payment, you will receive a response containing the payment's ID and initial status. An example response is provided below:
{
"paymentBulkId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "PendingProcessing"
}Duplicate Check
The system keeps a hash of submitted bulk payment files for 100 days to prevent duplicate processing:
- Identical files are rejected - Same content will be rejected even with different filenames
- Modified content is accepted - Changing any character in the file will pass the duplicate check
- Renaming files doesn't work - Simply changing the filename with identical content will be rejected
Error message: Duplicate submissions return "DuplicateFileUpload"
Payload too large.
Size of request or response is too big and therefore rejected
Unsupported media type.
Incorrect media type provided in Request Header “Accept” parameter.