We provide various methods to initiate payments.

The primary method is through our Payments API, which supports both single and bulk payments, in JSON format. The details of these options are explained further in this section.

We also offer the option to submit payments in the pain.001 format, which adheres to the ISO20022 standard in XML. For more information on this method, read how to Initiate payment with pain.001 & pain.002.

About the Payments API

The Payments API enables you to initiate payments either as single payments or bulk payments, depending on the volume and nature of your systems.

Single Payments
The Single Payments endpoint processes individual payments one at a time. It is suitable for use cases where payments are handled individually, such as companies with low payment volumes or systems that process payments individually in near-real time (interactive processing). If your company deals with small amounts of payments at low frequencies, the Single Payments endpoint is the appropriate choice.

Bulk Payments
The Bulk Payments endpoint processes multiple payments simultaneously. It is designed for companies with high payment volumes or systems that handle payments in batches or queues, processed at intervals. The response time for processing 1000 payments in bulk is faster than processing 1000 payments via the Single Payments endpoint.

📘

Find the right account

If you are initiating a payment for the first time and lack an overview of your available accounts click here for a guide on finding the correct account and account information for the debtorAccount.

Initiate a Single payment

To initiate a single payment, a POST request should be sent to the api/v1/payments/singles endpoint, described in details here: Single payments.

Content specifications Header

Content specifications Body

*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 (-)

Duplicate check

All single payments submitted via the Single Payments API undergo a duplicate check to ensure that the same payment is not processed twice. If two single payments with the same amount/currency, beneficiary name and address, debtor reference and execution date are submitted, the second payment will be rejected. The second payment will initially be placed in a PendingProcessing state before being rejected.

Occasionally, two single payments may run simultaneously and bypass the duplicate check due to parallel processing.

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.

Initiate a Bulk payments

To initiate a bulk payment, a POST request should be sent to the api/v1/payments/bulks endpoint. The content type for bulk payments is multipart/form-data. Here is a link to the relevant API reference Bulk payments.

Content specifications header

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.

*Allowed characters:

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 (–)

Example of CSV file content

123456789,DK1111000000010011,015,DKK,20,DKK,10012022,A,Financial Inst.Ltd.,DK1111000000010100,S,SXPYDKKKXXX,,MESSAGE,,,,SHA,,,DKK,hello1234567,45  
BOD,SOMETHING,FR - GRENOBLE 38100,N  
123456789,DK1111000000010100,010,DKK,20,DKK,10012022,A,Financial  
Inst.  
Ltd.,DK1111000000010011,S,SXPYDKKKXXX,,MESSAGE,,,,SHA,,,DKK,hello1234568,45  
BOD,SOMETHING,FR - GRENOBLE 38100,N

Partial bulk processing

When sending bulk files to the api/v1/payments/bulks endpoint, if some payments contain errors, they will be caught by our validations. In such cases, you will receive a rejection response with a list of errors, like the example below:

{  
  "type": "Csv",  
  "errors": [  
    {  
      "fieldIndex": 7,  
      "elementIndex": 1,  
      "errorCode": "RequestedExecutionDateDaysInPastThresholdViolation",  
      "errorDescription": "Requested Execution Date exceeds allowed number of days in the past."  
    }  
  ],  
  "canProceedWithErrors": true  
}

Properties explained

canProceedWithErrors:

Boolean property that informs you if BC Connect can continue processing the valid payment instructions from your bulk file. When this property is false, you can't proceed, and the file is rejected completely. When it's true, you can choose to continue.

ProceedWithErrors :

Boolean optional header parameter that allows you to continue with your bulk file in case of errors, given that canProceedWithErrors property is true. If you want to continue with the same file, you can resend it to /api/v1/payments/bulks by adding the ProceedWithErrors header parameter as true to signal that we may proceed with uploading the file. This action will initiate the valid payments in the file and disregard the invalid ones.

Click here to check the response schema for 400 Bad Request and the header parameters for the bulk payments endpoint.

The invalid payments can be retrieved from GET /api/v1/payments/singles and filter per
bulkId and from the GET /api/v1/reports/rejection-report. You can correct and then reinitiate the payments as singles, or another file can be uploaded only including the corrected payments.

Duplicate check

If two identical bulk files are submitted, one of them will be rejected. Changing a single character within the file will pass the duplicate check, and the payments will be sent for processing. However, if only the name of the file is changed, it will not pass the duplicate check and will be rejected. We keep a hash of submitted bulk payment files for 100 days to prevent duplicate processing.

Duplicate bulk payments will result in the error message: "DuplicateFileUpload".

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.

Cancel a payment

The API utilises Straight-Through-Processing, allowing valid payments to be directly sent to our core system for processing. Once a payment has been initiated, it can only be cancelled if it has a future execution date that has not yet passed.

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