Payment API

Initiate payments from a payment account.

Introduction
Payment details request.
Payment initiation status request.
Payment initiation request.
Cancels a payment initiation.
Periodic payment details request.
Periodic Payment initiation status request.
Periodic Payment initiation request.
Cancels a periodic payment initiation.
Bulk Payment initiation status request.
Bulk Payment initiation request.
Cancels a bulk payment initiation.

Introduction

Payment Initiation Service (PIS)

These endpoints provide the PISP possibilities for initiating payments, requesting a payment status and cancelling a payment.

Consumes

application/json
application/xml

Produces

application/json

Hosts

You can use the production host when you want to go live:

psd2.b2b.belfius.be:8443

psd2.b2b.banx.be:8443

Click the button below to download the open API specification.

Download

Example screen

Navigate to an endpoint to see sample code

Payment details request.

The PISP checks the details of a payment initiation. Only the following **payment products** are allowed: - ***sepa-credit-transfers*** - ***instant-sepa-credit-transfers*** - ***cross-border-credit-transfers*** Please note that the Authorization header is mandatory & must be provided with a bearer token. Caller receives the bearer token by standard OAuth2 authorization code grant flow, calling /token API with the authorization_code received at the end of payment initation request. Please refer to documentation in the "flow" section of the portal for details.

Parameters

payment-product Path required string

The single payment products. The following **payment products** are supported: - sepa-credit-transfers - instant-sepa-credit-transfers - cross-border-credit-transfers

payment-id Path required string

Payment reference.

example:

"1234-wertiq-983"

Authorization Header required string

The access token. Note that access-token is limited to a given type of request [here PIS]. The token itself should be passed as bearer token in Authorization header, like: "Bearer 987tghjkiu6trfghjuytrghj".

example:

"Bearer 987tghjkiu6trfghjuytrghj"

Request-ID Header required string

ID of the request. Must be unique. It has to be a valid UUID in V04 format.

example:

"99391c7e-ad88-49ec-a2ad-99ddcb1f7721"

Accept Header required string

It must be of type application/json including the API version number. [Accept:application/vnd.belfius.api+json; version=1].

example:

"application/vnd.belfius.api+json; version=1"

Accept-Language Header required string

Language. It can include language in ISO 639-1 format [example: fr]. Note that during redirection, Belfius screens are only available in French (fr) and Dutch (nl).

example:

"fr"

Client-ID Header required string

Client ID of registered PISP received after the onboarding.

example:

"l7957ffbdbcbf4496a8a406702aacbf539"

payment-id-type Query optional string

Type of Payment ID. Following Types are supported: - INTERNAL: Usage of the reference provided by Belfius in the response of the post payment API. - EXTERNAL: Usage of the reference provided by the PISP when initiating the payment.

example:

""

Response

{
  "debtor_account": {
    "iban": "BE54063301200997",
    "currency": "EUR"
  },
  "creditor_account": {
    "iban": "BE54063301200998",
    "bban": "123456789FW999999999",
    "country": "SE",
    "currency": "EUR",
    "bic": "BBVAESMM",
    "bank_national_id": "XXXXXXXXX"
  },
  "instructed_amount": {
    "currency": "EUR",
    "amount": "5877.78"
  },
  "creditor_name": "Creditor Name",
  "creditor_address": {
    "street": "string",
    "building_number": "string",
    "city": "string",
    "postal_code": "string",
    "country": "SE"
  },
  "purpose_code": "string",
  "remittance_information_unstructured": "Ref Number Merchant",
  "remittance_information_structured": {
    "reference": "string",
    "reference_type": "string",
    "reference_issuer": "string"
  },
  "charge_bearer": "string",
  "requested_execution_date": "2020-09-18",
  "endtoend_identification": "1232424kw54u1iu12o4141",
  "instruction_priority": "string",
  "psu_name": "Francois Dupont"
}

Headers

Response-ID: Same as Request-ID, received in request.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}

Name	Type	Description
debtor_account	object	Debtor Account Information. This is no longer mandatory. If filled the given account will be used to initiate the payment. If not filled the PSU will receive an account list while redirected to Belfius/Banx environment.	optional
iban	string	IBAN of an account. Note that the 2 letters identifying the IBAN's country should be upper case.	required
currency	string	The currency of the account compartment the PSU wants to use. * sepa-credit-transfers : MUST be EUR. EUR is default if not provided. * instant-sepa-credit-transfers : MUST be EUR. EUR is default if not provided. * cross-border-credit-transfers : The currency of the account compartment the PSU wants to use. EUR is default if not provided.	optional
creditor_account	object	Creditor Account Information.	required
iban	string	IBAN of an account. Note that the 2 letters identifying the IBAN's country should be upper case. * sepa-credit-transfers : required. * instant-sepa-credit-transfers : required. * cross-border-credit-transfers : conditional. Please refer to documentation in the "flow" section of the portal for details.	optional
bban	string	Basic Bank Account Number. * sepa-credit-transfers : n/a. * instant-sepa-credit-transfers : n/a. * cross-border-credit-transfers : conditional. Please refer to documentation in the "flow" section of the portal for details.	optional
country	string	ISO 3166 ALPHA2 country code.	optional
currency	string	The currency of the account compartment the PSU wants to use. * sepa-credit-transfers : MUST be EUR. EUR is default if not provided. * instant-sepa-credit-transfers : MUST be EUR. EUR is default if not provided. * cross-border-credit-transfers : The currency of the account compartment the PSU wants to use. EUR is default if not provided.	optional
bic	string	Bank Identifier Code. * sepa-credit-transfers : optional. * instant-sepa-credit-transfers : optional. * cross-border-credit-transfers : conditional. Please refer to documentation in the "flow" section of the portal for details.	optional
bank_national_id	string	Bank National ID. * sepa-credit-transfers : optional. * instant-sepa-credit-transfers : optional. * cross-border-credit-transfers : conditional. Please refer to documentation in the "flow" section of the portal for details.	optional
instructed_amount	object		required
currency	string	Payment currency for payment initiation. * sepa-credit-transfers : MUST be EUR. EUR is default if not provided. * instant-sepa-credit-transfers : MUST be EUR. EUR is default if not provided. * cross-border-credit-transfers : required. Please refer to documentation in the "flow" section of the portal to find the currencies accepted by Belfius.	required
amount	string	The amount given with fractional digits, where fractions must be compliant to the currency definition. The decimal separator is a dot. Example: Valid representations with up to two decimals are: * 1056 * 5768.2 * 5877.78	required
creditor_name	string	Creditor name.	required
creditor_address	object	Creditor address. * sepa-credit-transfers : n/a. * instant-sepa-credit-transfers : n/a. * cross-border-credit-transfers : required.	conditional
street	string		optional
building_number	string		optional
city	string		optional
postal_code	string		optional
country	string	ISO 3166 ALPHA2 country code.	required
purpose_code	string	Reason of Payment. * sepa-credit-transfers : n/a. * instant-sepa-credit-transfers : n/a. * cross-border-credit-transfers : conditional. Please refer to documentation in the "flow" section of the portal for accepted purpose code.	conditional
remittance_information_unstructured	string	Unstructured remittance information. * sepa-credit-transfers : optional. * instant-sepa-credit-transfers : optional. * cross-border-credit-transfers : conditional. Please refer to the ""flow"" section of the portal for countries where remittance information is required.	optional
remittance_information_structured	object	Structured remittance information. Only Belgian structured is accepted. * sepa-credit-transfers : optional. * instant-sepa-credit-transfers : optional. * cross-border-credit-transfers : n/a.	optional
reference	string		required
reference_type	string	SCOR	required
reference_issuer	string	BBA	required
charge_bearer	string	Conditional: Charge Bearer. ChargeBearerType1Code from ISO20022. * sepa-credit-transfers : n/a. * instant-sepa-credit-transfers : n/a. * cross-border-credit-transfers : required. DEBT CRED SHAR	conditional
requested_execution_date	string	Payment execution date. Sender may choose a specific future date on which payment has to be executed in ISO_8601 UTC date format [YYYY-MM-DD]. Default will be today or the next open business day. * sepa-credit-transfers - optional. * instant-sepa-credit-transfers - n/a. * cross-border-credit-transfers - optional.	optional
endtoend_identification	string	The reference provided by the PISP when initiating the payment. It has to be unique with maximum length of 35 chars. It will be returned back in the response.	required
instruction_priority	string	Priority of Payment. Some of these offered services are paying services for the PSU. You can consult our website to know the exact charges due. * sepa-credit-transfers - optional. * instant-sepa-credit-transfers - n/a. * cross-border-credit-transfers - optional. NORMAL URGENT	optional

Name	Type	Description
debtor_account	object	Debtor Account Information for periodic payment initiation.	optional
iban	string	IBAN of an account. Note that the 2 letters identifying the IBAN's country should be upper case.	required
currency	string	The currency of the account compartment the PSU wants to use for periodic payment initiation. * sepa-credit-transfers : MUST be EUR. EUR is default if not provided.	optional
creditor_account	object	Creditor Account Information for periodic payment initiation. Variable standing orders are only possible in favour of Belfius saving accounts.	required
iban	string	IBAN of an account. Note that the 2 letters identifying the IBAN's country should be upper case.	required
periodic_payment_type	string	Periodic Payment Type. Indicates whether the amount to be transferred will be the same each execution ("FIXED") or change depending on other variables ("VARIABLE"). FIXED VARIABLE	optional
instructed_amount	object		required
currency	string	Payment currency for periodic payment initiation. * sepa-credit-transfers : MUST be EUR. EUR is default if not provided.	required
amount	string	Amount to be transferred. It is mandatory when periodic_payment_type is FIXED. The amount given with fractional digits, where fractions must be compliant to the currency definition. The decimal separator is a dot. Example: Valid representations with up to two decimals are: * 1056 * 5768.2 * 5877.78	optional
minimal_amount	string	Minimum amount to keep on the orderer account. It is only applicable if periodic_payment_type is VARIABLE. If neither minimal nor maximal amount is filled in, the entire amount present on the account will be transferred in case of variable standing order. The amount given with fractional digits, where fractions must be compliant to the currency definition. The decimal separator is a dot. Example: Valid representations with up to two decimals are: * 1056 * 5768.2 * 5877.78	optional
maximal_amount	string	Maximum amount to transfer to beneficiary account. It is only applicable if periodic_payment_type is VARIABLE. If neither minimal nor maximal amount is filled in, the entire amount present on the account will be transferred in case of variable standing order. The amount given with fractional digits, where fractions must be compliant to the currency definition. The decimal separator is a dot. Example: Valid representations with up to two decimals are: * 1056 * 5768.2 * 5877.78	optional
creditor_name	string	Creditor name.	required
creditor_address	object	Creditor address for periodic payment initiation. * sepa-credit-transfers : n/a.	conditional
street	string		optional
building_number	string		optional
city	string		optional
postal_code	string		optional
country	string	ISO 3166 ALPHA2 country code.	required
remittance_information_unstructured	string	Unstructured remittance information for periodic payment initiation. * sepa-credit-transfers : optional.	optional
remittance_information_structured	object	Structured remittance information for periodic payment initiation. Only Belgian structured is accepted. * sepa-credit-transfers : optional.	optional
reference	string		required
reference_type	string	SCOR	required
reference_issuer	string	BBA	required
endtoend_identification	string	The reference provided by the PISP when initiating the payment. It has to be unique with maximum length of 35 chars. It will be returned back in the response.	required
start_date	string	Start date of the standing order. Sender may choose a specific date on which the first payment of the standing order has to be executed in ISO_8601 UTC date format [YYYY-MM-DD]. This date should be in the future. Default will be the next open business day. This date will also determine the recurring execution date for all frequencies other than "WEEKLY", e.g. if "2020-09-18" if used as start date with frequency "MONTHLY" the order will be executed on the 18th of each month (if open business day).	required
end_date	string	End date of the standing order. Sender may choose a specific date on which the last payment of the standing order has to be executed in ISO_8601 UTC date format [YYYY-MM-DD]. This date should be in the future. Please refer to documentation in the "flow" section of the portal for more information on how to correctly use the end date.	optional
frequency	string	Periodicity of the standing order. YEARLY BIANNUAL MONTHLY BIMONTHLY TRIMONTHLY QUATERLY WEEKLY	required
day_of_execution	string	Day of execution of standing order. It is mandatory if frequency is WEEKLY. MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY	optional

Introduction

Hosts

Example screen

Navigate to an endpoint to see sample code

Payment details request.

Parameters

payment-product Path required string

payment-id Path required string

Authorization Header required string

Request-ID Header required string

Accept Header required string

Accept-Language Header required string

Client-ID Header required string

payment-id-type Query optional string

Response

200 OK

400 Bad Request

Headers

error (string)

error_code (string)

error_description (string)

401 Unauthorized / authentification failure

Headers

error (string)

error_code (string)

error_description (string)

403 Forbidden

Headers

error (string)

error_code (string)

error_description (string)

404 Not found

Headers

error (string)

error_code (string)

error_description (string)

405 Method Not Allowed

Headers

error (string)

error_code (string)

error_description (string)

406 Not Acceptable

Headers

error (string)

error_code (string)

error_description (string)

408 Request Timeout

Headers

error (string)

error_code (string)

error_description (string)

409 Conflict

Headers

error (string)

error_code (string)

error_description (string)

415 Unsupported Media Type

Headers

error (string)

error_code (string)

error_description (string)

429 Too Many Requests

Headers

error (string)

error_code (string)

error_description (string)

495 SSL certificate error. Mutual TLS cannot be established. It may occur when an unregistered TPP or a PISP with an invalid/expired certificate is trying to access the APIs.

Headers

error (string)

error_code (string)

error_description (string)

500 Internal Server Error

Headers

error (string)

error_code (string)

error_description (string)

503 Service Unavailable

Headers

error (string)

error_code (string)