Payment API

Initiate payments from a payment account.

Payment initiation services (PIS) – PSD2 APIs

The PIS APIs provide a Belfius or Banx customer the possibility to initiate a payment or create a standing order using their account via a TPP application. The PIS APIs also provide the possibility to a Belfius client to initiate a bulk payment.

As soon as the payment initiation or the standing order contract has been received by Belfius/Banx and has been signed by the PSU, the TPP receives an authorization code if an access token wasn’t provided at the start of the process. The TPP can then use this authorization code to get an access token and a refresh token which can then be used for future initiations and cancellations.

The access token can also be used to retrieve the details (amount, accounts, …) of a payment initiation or standing order contract.

Finally, the TPP can retrieve the status of the payment initiation, the payment bulk or the standing order contract. To perform this call, a valid access token is not necessary.

Initiating and signing a payment

General flow

When a PSU would like to initiate a payment, a bulk payment or create a standing order in a TPP application, the TPP calls the corresponding PIS API and provides its specified parameters. More information on the parameters that should be provided in input is available below and in the “Documentation” section. Note that some of these offered services are paying services. You can consult Belfius/Banx rates on the respective websites.
If the TPP has the required access authorizations and all parameters are correct, the API responds with either:
- a message indicating that the payment has been successfully initiated. Belfius/Banx does not currently support SCA exemption for payment initiation, this case is therefore not currently applicable.
- a message indicating the payment initiation requires a SCA from the PSU. In this case, the TPP also receives a URL in the response. The PSU should be redirected to Belfius/Banx environment using this URL to which a “state” has been added by the TPP. This “state” will help the TPP identify the call coming from the Belfius/Banx environment when the required authentication steps are finalized.
- a message indicating the payment initiation is being validated. This will be the case for all bulk payments. The TPP will have to wait until the validation is completed before enabling the PSU to sign the bulk payment initiation.
The PSU must be redirected to the Belfius/Banx environment to sign the payment initiation via the redirection URL provided.
The PSU signs the payment initiation in the Belfius/Banx environment. If no payment account was indicated as debtor_account, the PSU will have the possibility to select a payment account from a list.
The successful signature is confirmed to the PSU, an authorization code is generated. The PSU is directed back to the TPP via the indicated redirect URL, along with the authorization code.
If desired the TPP can exchange the authorization code for access and refresh tokens, i.e. to retrieve the payment initiation details or to cancel the payment.

Initiating a single payment

• POST /payments/{payment-product}

A Belfius customer can initiate the following payment products in the TPP application:

sepa-credit-transfers
instant-sepa-credit-transfers
cross-border-credit-transfers

A Banx customer can initiate the following payment products in the TPP application:

sepa-credit-transfers
instant-sepa-credit-transfers

The below table aims to give a quick overview of the body request parameters regarding the payment product:

	sepa-credit-transfers	Instant-sepa-credit-transfers	cross-border-credit-transfers
debtor_account – iban	optional	optional	optional
debtor_account – currency	EUR as default	EUR as default	please see further
charge_bearer	n/a	n/a	required
creditor_account – iban	required	required	conditional
creditor_account – bban	n/a	n/a	conditional
creditor_account – bic	optional	optional	conditional
creditor_account – bankNationalID	n/a	n/a	conditional
creditor_account - currency	n/a	n/a	conditional
creditor_name	required	required	required
creditor_address	n/a	n/a	conditional
endtoend_identification	required	required	required
instructed_amount – amount	required	required	required
instructed_amount – currency	EUR as default	EUR as default	required
instruction_priority	optional	n/a	optional
purpose_code	n/a	n/a	please see further
remittance_information_structured	optional	optional	n/a
remittance_information_unstructured	optional	optional	optional
requested_execution_date	optional	n/a	optional

Please also note that Belfius and Banx allow their clients to choose some of its security features: daily/weekly limits or accepted destination countries for payments are among them. If the payment initiation is not accepted for one of these reasons, Belfius/Banx will return a customer profile error.

SEPA credit transfer

This payment product should be used to initiate a SEPA credit transfer.
I.e. : a payment in euro where both accounts (debtor and creditor) are in euro and within the SEPA zone.
This payment will be executed by Belfius/Banx following the SEPA rules.

Please also note the following information:

Urgent (same value date for debtor and creditor) payment initiation is only allowed on Belfius professional accounts. Also note that this is a paying service for our customers.
In case of structured communication, only Belgian structured communication is accepted by Belfius.

Instant SEPA credit transfer

This payment product should be used to initiate an instant SEPA credit transfer.
I.e. : a payment in euro where both accounts (debtor and creditor) are in euro and within the SEPA zone that should be executed immediately (within 10 seconds). This payment can be executed 24/7/365.
Instant payments can be done throughout all of the SEPA zone.
This payment will be executed by Belfius/Banx following the SEPA rules.

Please also note the following information:

Instant payment initiation is a paying service for some of our customers. Using this payment product could therefore be invoiced to these clients.
In case of structured communication, only Belgian structured communication is accepted by Belfius.

Cross border credit transfer

This payment product should be used to initiate a non-SEPA credit transfer.
I.e : a payment in euro outside the SEPA zone or a payment in currency within or outside the SEPA zone.

Please find in this document a summary of the accepted destination countries, the accepted currencies and the accepted purpose codes for each country/currency.

Please also note the following information:

Banx customers cannot initiate this type of payment
Urgent (same value date for debtor and creditor) payment initiation is only allowed on Belfius professional accounts.
Non-SEPA payment initiation is a paying service.

Creating a standing order

• POST /periodic-payments/sepa-credit-transfers

A Belfius customer can create a fixed or a variable standing order. A Banx customer can create only a fixed standing order.

The only payment product accepted for standing order creation is sepa-credit-transfer.

Fixed standing order

With this standing order type, a fixed amount will be transferred at a specific frequency to the beneficiary account.

Please note the following information:

If a periodicity other than weekly is used, the start_date will also determine the date of execution. It is not possible to specify an execution_date different from the start_date. E.g. for a monthly standing order with a start date on the 20th of September 2021, the execution of the standing order will be on the 20th of every month (if the 20th is a bank working day).
If a periodicity other than weekly is used and if an end_date is mentioned, the end_date helps to determine the period in which will happen the last execution of the standing order E.g. for a monthly standing order with a start date on the 20th of September 2021 and an end date on the 10th of September 2022, the standing order will be executed every 20th of the month from September 2021 until and including September 2022.
Indeed the 10th of September is in September, the last execution of the standing order will therefore be in September.
If the standing order execution date is not a bank working day, the standing order will be executed on the next open business day. Note that specific measures are taken at the end of the year, in order to execute the standing order in the correct fiscal year.

Variable standing order

With this standing order type, a variable amount will be transferred at a specific frequency to the beneficiary account. The amount will be calculated based on the two following parameters

minimal_amount = the minimum amount that should be kept on the ordering account
maximal_amount = the maximum amount to be transferred to the beneficiary account

If neither minimal nor maximal amount is filled in, the entire amount present on the account will be transferred.

Variable standing orders can only be used to transfer money to Belfius saving accounts, no other.

Please note the following information:

Banx customers cannot initiate this type of standing order
If a periodicity other than weekly is used, the start_date will also determine the date of execution. It is not possible to specify an execution_date different from the start_date. E.g. for a monthly standing order with a start date on the 20th of September 2021, the execution of the standing order will be on the 20th of every month (if the 20th is a bank working day).
If a periodicity other than weekly is used and if an end_date is mentioned, the end_date helps to determine the period in which will happen the last execution of the standing order E.g. for a monthly standing order with a start date on the 20th of September 2021 and an end date on the 10th of September 2022, the standing order will be executed every 20th of the month from September 2021 until and including September 2022.
Indeed the 10th of September is in September, the last execution of the standing order will therefore be in September.
If the standing order execution date is not a bank working day, the standing order will be executed on the previous open business day. Note that specific measures are taken at the end of the year, in order to execute the standing order in the correct fiscal year.

Initiating a bulk payment

• POST /bulk-payments/{bulk-payment-product}

Only Belfius business customers can initiate file payments. It is possible to initiate pain.001 and csv payments. Note that csv files should be saved as csv UTF-8.

Please note that a payment file initiated through the POST /bulk-payments API can contain several payment bulks.

Please also note that validation of a file payment can take up to several minutes. The POST /bulk-payments API will therefore not return an SCA URL to sign the file. This URL will be returned by the GET /status API when the validation is finished.

HTTP signature

The following document will help you create the requested signature.

PSU signature

When being redirected to the Belfius/Banx environment, the PSU will be able to authenticate using one of the authentication methods proposed by Belfius or Banx.

Belfius/Banx allows the same authentication methods as in its channels. Note that depending on the transaction risk some SCA methods might not be allowed.

Also note that biometrics availability is depending on the configuration by the PSU within Belfius/Banx. If the PSU has activated biometrics for its Belfius/Banx channels, these SCA methods will be available through the redirection flows.

Belfius allows multi-signature for payments and bulk payments. If the payment should be signed by several PSU’s, the first signature should always occur via the redirection flow (using the redirect SCA URL returned by Belfius). The additional signatures should occur via the PSU’s Belfius channel.

Note that for security reasons, the SCA URL that is provided by Belfius is only valid for a few minutes. After this, the payment request or status request in case of bulk payment initiation should be done again to retrieve a valid URL.

Retrieving the status

A Belfius or Banx customer can retrieve the status of a payment transaction initiated earlier in the TPP application or of a standing order contract created via the TPP application.

Please note that to retrieve the status, the TPP must provide the payment_ID but no access token is required in the API call.

General flow

When a PSU would like to retrieve the status of a payment initiation or of a standing order contract, the TPP calls this API with the payment-ID. This communication is secured using eIDAS certificates. If all the provided details are valid, Belfius will return the status.

Status of a single payment

• GET /payments/{payment-product}/{payment-ID}/status

This API can be used with an external reference (i.e. given by the TPP, the endtoend_reference) or with an internal reference (i.e. the reference given by Belfius in the API answer, the payment_id). If not specified otherwise in the request body, Belfius/Banx expects the internal reference to be used in the input.

Note that Belfius/Banx returns the following statuses:

[RJCT] Payment initiation rejected
[RCVD] Payment initiation received
[PATC] Payment initiation waiting for signature
[CANC] Payment initiation cancelled following a manual intervention or a time out or in case of technical error in our chains or other
[PDNG] Payment initiation accepted after technical checks/ signature, waiting to go to another status
[ACSP] Settlement in process/Waiting

Instant SEPA credit transfer

If an instant payment was initiated, the PSU has information on the correct execution of the payment during its redirection to the Belfius/Banx environment.

Note that instant payments cannot be in status “PDNG”.

Status of a standing order contract

• GET /periodic-payments/sepa-credit-transfers /{payment-ID}/status

Belfius/Banx returns the following statuses in case of standing order

[PATC] Standing order creation waiting for signature
[CANC] Standing order cancelled following a manual intervention or a time out or in case of technical error in our chains or other
[PDNG] Standing order accepted after technical checks/ signature, waiting to go to another status
[ACWP] Active standing order. Payment transaction will be executed accordingly to the standing order characteristics

Status of a bulk payment

• GET /bulk-payments/{bulk-payment-product} /{bulk-payment-ID}/status

Belfius returns the following statuses in case of file payment. Note that Belfius will return the global status of the file as well as the status of the different payment bulks contained in the file.

[RJCT] Bulk payment rejected
[RCVD] Bulk payment received
[PATC] Bulk payment waiting for signature
[CANC] Bulk payment cancelled following a manual intervention or a time out or in case of technical error in our chains or other
[PDNG] Bulk payment accepted after technical checks/ signature, waiting to go to another status
[ACSP] Settlement in process/Waiting

Note that when validation of a file payment is finished, the GET /status bulk API will return an SCA URL to sign the bulk.

Retrieving the details

A Belfius or Banx customer can retrieve the details of a payment transaction initiated earlier in the TPP application or of a standing order contract created via the TPP application.

Please note that to use this API, the TPP must provide a valid access token except when cancelling a file payment. This access token can be received after calling the token API using the authorization code provided by Belfius/Banx at the end of the initiation. All details on this flow can be found in the Flows section of the consent API documentation.

General flow

When a PSU would like to retrieve the details of a payment initiation or of a standing order contract, the TPP calls this API with the payment-ID and access token. This communication is secured using eIDAS certificates. If all the provided details are valid, Belfius will return the details.

Details of a single payment

• GET /payments/{payment-product}/{payment-ID}/details

Belfius/Banx will return following details for a single payment initiation. For some transactions more details can be returned as available, please check documentation for all possible details.

psu_name: the name of the PSU who has initiated the payment
debtor_account: the IBAN used by the PSU
creditor_account: the beneficiary account
instructed_amount: the amount of the transaction
creditor_name: the beneficiary name
endtoend_identification: the reference provided by the TPP

Details of a standing order contract

• GET /periodic-payments/sepa-credit-transfers/{payment-ID}/details

Belfius/Banx will return following details for a standing order contract. For some transactions more details can be returned as available, please check documentation for all possible details.

psu_name: the name of the PSU who has created the standing order
debtor_account: the IBAN used by the PSU
creditor_account: the beneficiary account
instructed_amount: the amount of the transaction
creditor_name: the beneficiary name
endtoend_identification: the reference provided by the TPP
start_date: the date of the first execution of the contract
frequency: the frequency of the contract execution

Cancellation

A Belfius or Banx customer can cancel an uncompleted payment transaction, an uncompleted file payment or an active standing order contract initiated earlier in the TPP application.

General flow

When a PSU would like to cancel a payment initiation or a file payment initiation or a standing order contract, the TPP calls this API with the earlier received access token. This communication is secured using eIDAS certificates. If all the provided details are valid, and the payment initiation or the standing order is in a cancellable status (see further), Belfius/Banx responds with the confirmation.

Cancel a single payment

• DELETE /payments/{payment-product}/{payment-ID}

A Belfius or Banx customer can cancel an uncompleted payment transaction initiated earlier in the TPP application.

SEPA credit transfer

Payment initiation can be cancelled only if

It is unsigned = with statuses RCVD or PATC
It is future dated = with status PDNG
It is in recycling = with status PDNG

Instant SEPA credit transfer

The only available statuses for cancellation are RCVD and PATC

Cross border credit transfer

Cross-border-credit-transfer cannot be deleted.

Cancel a standing order contract

• DELETE /periodic-payments/sepa-credit-transfers /{payment-ID}

Standing orders in all statuses can be cancelled.

Please note that an ongoing occurrence cannot be cancelled. The standing order contract will be deleted as from the next occurrence.

Cancel of a bulk payment

• DELETE /bulk-payments/{bulk-payment-product} /{bulk-payment-ID}/

File payments in the following statuses can be cancelled

It is unsigned = with statuses RCVD or PATC
It is future dated = with status PDNG
It is in recycling = with status PDNG