Initiate payments

About the Payments API

The Payments API allows you to initiate payments in the form of single payments or bulk payments. Which endpoint to use depends on the volume of payments and the nature of your systems.

The Single Payments endpoint is designed to process one payment at a time. This endpoint is suited for use cases wherein payments are handled individually, e.g. companies operating with low volumes of payments and companies whose systems process payments individually in near-real time (interactive processing). If your company deals with small amounts of payments and at low frequencies, you would choose the Single Payments endpoint.

The Bulk Payments endpoint is designed to process multiple payments at the same time. This endpoint is suited for companies operating with large volumes of payments and companies whose systems operate with payments in batches or queues that are processed at intervals. The response-time for 1000 payments in a bulk is considerably faster than 1000 payments via the Single Payments endpoint, due to overhead in each request.

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

Before initiating a payment

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.

How to initiate a Single Payment

To initiate a single payment, a POST request should be sent to the api/v1/payments/singles endpoint. Below are the specifications for the parameters in the header and body and an example of the body of an initiated payment. The content type of single payments is application/json.

Content specifications Header

ParameterRequiredAllowed inputDescriptionExample
X-MessageReferenceOptionalStringUnique reference of the HTTP request. If left blank this field will be populated with a GUID6198eb60-d1dd-4aad-9bbd-b01a49214e62

Content specifications Body

ParameterRequiredAllowed inputDescriptionExample
requestedExecutionDateMandatoryYYYY-MM-DDThe date on which you would like your payment to be processed and debited from your Debtor Account2021-12-05
debtorAccount
accountMandatoryIBAN or accountAccount from which funds will be debitedDK1111111111111111
financialInstitution
Mandatory if Debtor Account is not an IBAN
Optional otherwise
Bank Identifier Code (BIC) or a National Clearing Code (NCC)Financial Institution where Debtor Account resides
SXPYDKKKXXX
SC083002
country
Mandatory if Creditor Account is not an IBAN
Optional otherwise
ISO Country CodeCountry of sender’s bankDK
debtorVibanOptionalIBANVIBAN belonging to the chosen account. This field should be populated if you wish to use funds from a specific VIBANDK1111111111111111
debtorReferenceOptionalMaximum length: 35. Allowed characters*Own reference which can be used for your own reconciliation. This value can be found on the reconciliation and rejection reports under User Reference. This field is purely for own reference, i.e. it is not part of the resulting paymentDebtor reference from your system
debtorNarrativeToSelfOptionalMaximum length: 35. Allowed characters*Dual purpose. Narrative to self: This field is purely for your own reference, i.e. it is not part of the resulting paymentFree text field
currencyOfTransferMandatoryFormat of Alpha 3 ISO 4217Currency of the amount that will be transferred to the creditor. Only supported currencies allowedEUR
Amount
currencyMandatoryFormat of Alpha 3 ISO 4217Currency of the amount. Only supported currencies allowedEUR
amountMandatoryMust 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 CurrencyInstructed amount
Valid examples (GBP): 100 | 100. | 100.00
Invalid examples (GBP): 1,100 | 1,100.00 | 1100.000
chargebearerMandatorySHADetermines which of the parties will be charged the payment fee. Only allowed value is SHA (shared), though will be overwritten if other preferences are set at account level.SHA
remittanceInformation
line1OptionalMaximum length: 35. Allowed characters*. Illegal characters**Line 1 of the textual information passed from Debtor to Creditor as part of the transferFree text field
line2OptionalMaximum length: 35. Allowed characters*. Illegal characters**Line 2 of the textual information passed from Debtor to Creditor as part of the transferFree text field
line3OptionalMaximum length: 35. Allowed characters*. Illegal characters**Line 3 of the textual information passed from Debtor to Creditor as part of the transferFree text field
CreditorId
Optional
Mandatory if creditorAccount is left blank
GUIDID 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 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
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
SC123456
country
Mandatory if Creditor Account is not an IBAN
And CreditorId is not populated
Optional otherwise
ISO Country CodeCountry of receiver’s bankDE
creditorNameMandatory if payment targets institutions other than Banking CircleMaximum length: 35. Allowed characters*. Illegal characters**Legal name of creditorBeneficiary name
creditorAddress
line1
Mandatory if payment targets institutions other than Banking Circle
Optional otherwise
Maximum length: 35. Allowed characters*. Illegal characters**Line 1 detailing the address of the CreditorAddress line 1
line2OptionalMaximum length: 35. Allowed characters*. Illegal characters**Line 2 detailing the address of the CreditorAddress line 2
line3OptionalMaximum 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
Address line 3
Example: DK – 2900 Hellerup

*) Allowed characters – Any of:

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 – Any of:

Field only composed of blank characters (space)

First character is colon (:) or hyphen (–)

Example of body

{
  "requestedExecutionDate": "2021-12-06",
  "debtorAccount": {
    "account": "DK1111111111111111",
    "financialInstitution": "SXPYDKKK",
    "country": "DK"
  },
  "debtorViban": null,
  "debtorReference": "UserRef",
  "debtorNarrativeToSelf": null,
  "currencyOfTransfer": "EUR",
  "amount": {
    "currency": "EUR",
    "amount": 11
  },
  "chargeBearer": "SHA",
  "remittanceInformation": {
    "line1": "Remittance Info",
    "line2": "Remittance Info 2",
    "line3": null,
    "line4": null
  },
  "creditorId": null,
  "creditorAccount": {
    "account": "DE1111111111111111",
    "financialInstitution": "WIREDEMM",
    "country": "DE"
  },
  "creditorName": "Creditor Name",
  "creditorAddress": {
    "line1": "Address 1",
    "line2": "Address 2",
    "line3": "Address 3"
  }
}

Duplicate check

All submitted payments via the Single Payments API go through a duplicate check to ensure that the same payment is not processed twice.

If two single payments are submitted with the same amount, receiver and execution date, the second payment will be rejected. Note that the second payment will go into PendingProcessing before it is Rejected.

As we run processes in parallel, two single payments can, on rare occasions, both run at the same time and as a result miss the duplicate check.

How to initiate a Bulk Payment

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.

Content specifications header

ParameterRequiredAllowed inputDescriptionExample
X-Content-typeOptionaltext/csvv0Specifying content type. Currently supported type is "text/csvv0"text/csvv0
X-MessageReferenceOptionalStringUnique reference of the HTTP request. If left blank this field will be populated with a GUID6198eb60-d1dd-4aad-9bbd-b01a49214e62
X-ChannelOptionalchannel/apiChannel reference of the paymentchannel/api
ProceedWithErrorsOptionaltrue or false
Allow Bulk payment to be partially accepted. Read more about partial bulk here
Default: false
false

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.

FieldParameterRequiredAllowed inputDescriptionExample
1Debtor Customer IDMandatory (for technical reasons)9-digit NumericCustomer ID for the debtor account. Field is not utilized, but needs to be populated with a value to ensure that file is read properly999999999
2Debtor AccountMandatoryIBANAccount from which you want funds debited DK4789000000012345
3Debtor Account Branch CodeOptional010The bank branch for the debtor account is always 010010
4Debtor Account CurrencyOptionalAlphabeticThe currency for the debtor account populated in field 2EUR
5AmountMandatoryMust be larger than zero. Separators can not be includedInstructed amountValid examples (GBP): 100 | 100. | 100.00 . Invalid examples (GBP): 1,100 | 1,100.00 | 1100.000.
6Currency of TransferMandatoryAlphabetic. Format of Alpha 3 ISO 4217Currency of the amount that will be transferred to the creditorEUR
7Requested Execution DateMandatoryDDMMYYYYThe 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
8Payment TypeOptionalA'A' (for ad-hoc/general payment type)A
9Creditor NameMandatory if payment targets institutions other than Banking CircleMaximum length: 35 . Allowed characters*. Illegal characters**Name of the creditor that will receive fundsCompany A
10Creditor AccountMandatoryIBAN 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
11Transfer ModeOptionalS'S' for SWIFTS
12Creditor 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: SC123456
FW123456789
13Beneficiary e-mailOptionalE-mailEmail of the beneficiary. The field does not carry additional functionalityxxx@bankingcircle.com
14Remittance Information Line 1OptionalMaximum length: 35 . Allowed characters*. Illegal characters**Line 1 of the textual information passed from Debtor to Creditor as part of the transferFree text field
15Remittance Information Line 1Optional***Maximum length: 35 . Allowed characters*. Illegal characters**Line 2 of the textual information passed from Debtor to Creditor as part of the transferFree text field
16Remittance Information Line 3Optional***Maximum length: 35 . Allowed characters*. Illegal characters**Line 4 of the textual information passed from Debtor to Creditor as part of the transferFree text field
17Remittance Information Line 4Optional***Maximum length: 35 . Allowed characters*. Illegal characters**Line 4 of the textual information passed from Debtor to Creditor as part of the transferFree text field
18Charge BearerMandatoryValue: SHAOnly allowed value is SHASHA
19Debtor Narrative to SelfOptionalMaximum length: 35. Allowed characters*Dual purpose: Internal reference for client OR Virtual International Bank Account Number (VIBAN): the IBAN of one of your VIBANsFree text field
20Narrative for CreditorOptionalMaximum length: 35. Allowed characters*Additional narrative. The field has no functional impact and not included in reporting.Free text field
21Amount CurrencyMandatoryAlphabetic
Currency of the Amount
Amount Currency must match one of
Debtor Account Currency. Example: I would like 100 EUR from my EUR account set 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
22Debtor ReferenceOptionalMaximum length: 35. Allowed characters*Debtor own reference. Own reference which can be used for own reconciliation.Debtor reference from your system
23Creditor Address Line 1
Conditional***
Mandatory if payment targets other institutions than Banking Circle
Maximum length: 35. Allowed characters*. Illegal characters**Line 1 detailing the address of the Creditor. Mandatory: Only for payment targeting other institutions than Banking CircleFree text field
24Creditor Address Line 2Optional***Maximum length: 35. Allowed characters*. Illegal characters**Line 2 detailing the address of the CreditorFree text field
25Creditor Address Line 3Optional***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/city name with postal code.
Examples: DK - 2900 Hellerup | GB - London EC2M 4AY
26IntracompanyOptionalN'N' can be usedN

*) Allowed characters – Any of:

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 – Any of:

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 /api/v1/payments/bulks endpoint, if some of the payments contain errors, they are caught by our validations. If so, you will receive the following rejection response with a list of errors:

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

canProceedWithErrors is a Boolean property that informs you if Banking Circle 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 is a 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.

Check 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 the two will be rejected. A change of a single character within the file will make the file pass the duplicate check and the payments will be sent to processing. If only the name of the file is changed, it will not pass the duplicate check and thus be rejected. We keep a hash of submitted Bulk Payments files for 100 days to ensure that two exact files will not be sent to processing twice.

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

After initiating a payment

When a payment has been successfully sent you will receive a response with the ID of the payment and the initial status of the payment. An example response is listed below.

{
  "paymentBulkId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "None"
}

A guide for looking up the status of a payment can be found here along with a chapter on potential errors.