Payment API

Initiate payments from a payment account.

Payment initiation services (PIS) – PSD2 APIs

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

As soon as the payment or the standing order contract has been received by Belfius/Banx and signed by the customer, 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 TPP can also 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

  1. When a customer 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 parameter that should be provided in input are present 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.
  2. If the TPP has the required access authorizations, 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 an SCA from the customer . In this case, the TPP application also receives a URL in the response. The customer should be redirected to Belfius/Banx environment using this URL to which a “state” has been added.
    • 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.

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 required required required
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_name required required required
creditor_address n/a n/a required
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 required
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 payment are among them.

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 following the SEPA rules.

Please also note the following information:

  • Urgent (same date value for debtor and creditor) payment initiation is only allowed on Belfius professional account. Also note that this is a paying service for the customer.
  • 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.
Instant payment can be done thru all the SEPA zone.
This payment will be executed by Belfius following the SEPA rules.

Please also note the following information:

  • Instant payment initiation is a paying service for the customer.
  • In case of structured communication, only Belgian structured communication is accepted by Belfius.

Cross border credit transfer

This payment product should be used to initiation 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 the document a sum up of the accepted destination countries, the accepted currencies and the accepted purpose code for each country/currency.

Please also note the following information:

  • Banx customer cannot initiate this type of payment
  • Urgent (same date value for debtor and creditor) payment initiation is only allowed on Belfius professional account.
  • 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 transfer at a specific frequency to the beneficiary account.

Please note the following information:

  • if a periodicity different than weekly is used and if an end_date is mentioned, the end_date helps determining the period in which will happen the last execution of the standing order i.e. 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 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 transfer 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 orderer account
  • maximal_amount = the maximum amount to be transferred to the beneficiairy 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 customer cannot initiate this type of standing order
  • if a periodicity different than weekly is used and if an end_date is mentioned, the end_date helps determining the period in which will happen the last execution od the standing order
    i.e. 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 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 customer can initiate file payments. It is possible to initiate pain.001 and csv payments. Note that csv file should be saved as csv UTF-8.

Please note that a payment file initiated thru 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 return by the status API when the validation is finished.

HTTP signature

The following document will help you create the requestedsignature.

PSU signature

When being redirected to 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 that in its channels. Note that depend on the transaction risk some SCA methods might not be allowed.

Also note that biometrics availability is depending on the configuration of the PSU within Belfius/Banx. If the PSU has activated biometrics for its Belfius/Banx channels, these SCA methods will be available thru 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 reason, the SCA url that is provided by Belfius is only valid for a few minutes. After this, the payment request should be done again to retrieve a valid url.


Retrieving the status

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

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

General flow

  1. When a customer would like to retrieve the status of a payment initiation or of a standing order contract, 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 expect the internal reference to be used in the input.

Note that Belfius returns the following status

  • [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 customer 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 returns the following status 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
  • [ACWP] Active standing order. Payment transaction will be executed accordingly to the standing order characteristics
  • [PDNG] Standing order accepted after technical checks/ signature, waiting to go to another status

Status of a bulk payment

Get /bulk-payments/{bulk-payment-product} /{bulk-payment-ID}/status

Belfius returns the following status 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 return an SCA url to sign the bulk.

Cancellation

A Belfius or a Banx customer can cancel an uncompleted payment transaction, an uncompleted file payments or an active standing order initiated earlier in 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

  1. When a customer would like to cancel a payment or file payment initiation or a standing order, 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 respond with the confirmation.

Cancel a single payment

A Belfius or a 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 futured 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 of a standing order contract

Delete /periodic-payments/sepa-credit-transfers /{payment-ID}

Standing orders in all statuses can be cancelled.

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 futured dated = with status PDNG
  • It is in recycling = with status PDNG