Payment API

Which type of account can be used to initiate a payment within a TPP application?

All Belfius and Banx payment accounts can be used to initiate a payment. This includes Business, Corporate and Public Segment accounts.

Note that to be eligible for PSD2, a payment account should be managed in one of the Belfius electronic channels (Belfius Mobile, Belfius Direct Net – Business, Belfius Web) or in the Banx Mobile application. If this is not the case, the account cannot be used to initiate a payment.

Also note that if the PSU blocked one of the digital channel subscriptions, the payment initiation may not be possible for security reasons. The PSU should unblock their digital channel to continue enabling PSD2. The PSU can contact Belfius contact center or Belfius branches to guide them through the procedure.

Is it required to provide an IBAN account in input for the payment initiation?

No account in input is required. If no account IBAN was provided in input of the API, an account list will be presented to the PSU after redirection to the Belfius/Banx environment.

To use the API without account in input, it is necessary to omit the field “debtor_account” entirely, it is not allowed to send an empty “debtor_account”. If you add the field to your request, it must still be filled with an IBAN.

The PSU account is a payment account, but the payment initiation is in error?

There can be several causes of this error. Please note that each client can choose its payment security parameters for each account, including daily/weekly limits or accepted destination countries for payments. The PSU can contact Belfius contact center or Belfius branches to help change these settings.

Does Belfius support multi-signature?

Yes, 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 multi-signature is not available for standing orders as this feature is not available in Belfius channels.

Note that Banx does not support multi-signature as this feature is not available in Banx app.

Does Belfius check the account balance before initiating the payment?

For payments that are directly executed a check of the account balance will be performed. In case the funds are not available, Belfius will send back an error to the TPP. Note that when PSU chooses the debtor account from a list, the PSU has the possibility to choose another account if the first selected account had insufficient balance.

For payment initiations with an execution date in the future, the balance check is performed on the specified date.

The PSU has signed its payment initiation successfully in Belfius/Banx environment, does that mean that the payment will be executed?

As in the Belfius/Banx channels, after a successful payment initiation signature, the payment is recorded and will be debited from the PSU payment account. For payments that are directly executed a check of the balance will be performed.

For payment initiations with an execution date in the future, this will only happen if the balance on the PSU account is sufficient at the specified date.

The completion of a payment initiation depends on a number of factors beyond the control of Belfius/Banx. A successful payment initiation signature by the PSU is therefore not a guarantee that the payment will be credited on the beneficiary account.

How can I retrieve an access-token in the payment initiation flow?

If the payment initiation was done without using an access-token in the Authorization header, the TPP will receive an authorization code in the callback URL after a successful PSU authentication.

This code can be used to retrieve access and refresh tokens linked to the PIS scope. This can be done by calling the POST /token API using the authorization code received and with “access_token” as grant_type. The POST /token API will then return the access and refresh tokens.

If the authorization code was exchanged for an access-token, this token can then be added to the header of additional payment initiations. It is not possible to obtain an access-token prior to a first successful payment initiation.

Should we pass an access-token in the Authorization header when posting a payment initiation?

This is your choice.

• If you are passing an access-token in the Authorization header: Belfius/Banx will not send back an authorization code at the end of the flow. In case the PSU wants to cancel the payment initiation or retrieve the payment details, you will need to use the refresh-token previously retrieved for this PSU and this scope to get a valid access-token.
• If you are not passing an access-token in the Authorization header: Belfius/Banx will send back an authorization code at the end of a successful redirection flow. In case the PSU wants to cancel the payment initiation or retrieve the payment details, you will need to use this authorization code to retrieve a valid access-token.

Should we pass an access-token in the Authorization header when retrieving the payment initiation status?

No, this is not necessary.

Should we pass an access-token in the Authorization header when retrieving the payment initiation details?

Yes, a valid access-token must be used to retrieve payment initiation details.

The POST /bulk-payment request does not return a redirection URL, is this normal?

Yes, it is normal. This is specific for the file initiation flow.

Belfius has to validate the file sent by the TPP. This can take some time (more than a few seconds). Therefore the redirection URL will not be returned during the PIS request.

The redirection URL will be returned once the file is validated by Belfius in the GET /status API.

Calling the GET /status API will therefore be necessary in the file initiation flow.

Note that if the GET /status API does not return a URL, this means that the file is not validated yet (or cannot be signed anymore). The TPP should then call the GET /status API again a few seconds later.

Which XML-format is supported by Belfius for bulk payments?

Belfius follows the EPC rulebooks and guidelines regarding pain.001, more information on this can be found here: SEPA XML.

The PSU wants to cancel an unsigned payment initiation, is this possible?

As explained in the Flows section, a valid access-token is required to cancel a single payment initiation. This means the PSU needs to first complete a successful payment initiation, which will return the authorization code to exchange for the access-token. If this was done, following payment initiations could be cancelled if unsigned.

Please note an unsigned single payment initiation will be automatically cancelled after 60 minutes.

How to create a HTTP-signature?

For PIS a HTTP-signature is necessary, information on how to create this can be found here: HTTP-signature.pdf.