Payment API

Initiate payments via a SEPA transfer from a Belfius account.

Introduction

PISP

This API provide the possibility for a TPP to initiate a SEPA payment on behalf of a Belfius customer.

Consumes
  • application/json
Produces
  • application/json

Hosts

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

https://psd2.b2b.belfius.be:8443

Click the button below to download the open API specification.

Download

Example screen

Navigate to an endpoint to see sample code


SEPA transfer.

The initiating party [customer/PISP] sends a create payment message to the forwarding agent or debtor agent that specifies the payment initiation request.


Request

Name Type Description
iban string Account IBAN.
name string Account Name.
iban string National Account number.
bic string Bank Identifier Code.

Parameters

Authorization Header optional string

Access token to be passed as a header.Scope of this access-token is limited to a given type [e.g. PIS] and given IBAN. Token itself should be passed as bearer token in Authorization header like:"Bearer 987tghjkiu6trfghjuytrghj".

Code-Challenge-Method Header optional string

PKCE code-challenge-method as per RFC https://tools.ietf.org/html/rfc7636. It is mandatory if there is no valid Authorization header present.

Code-Challenge Header optional string

PKCE code-challenge as per RFC https://tools.ietf.org/html/rfc7636. It is mandatory if there is no valid Authorization header present.

Request-ID Header required string

Request id to be passed as custom header. It will be used as sort of correlation id for logging and tracting purposes.

Accept Header required string

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

Content-Type Header required string

It should be application/json. It may optionally include charset.

Accept-Language Header required string

Accept-Language header field sent by the Client terminal. It can include language in ISO 639-1 format [example-:fr]. If no Accept-Language header is present or if it is present with a language which is not at all known to server, HTTP 406[Not Accepted] will be returned.

example:

"fr"
Client-ID Header required string

Client ID of registered TPP.

Redirect-URI Header required string

Redirect-URI of the client.

Signature Header required string

JWT containing JWS in signatue section(representing the signature of payment payload) and the actual payload in JWT body. Recommended Algorithm - ECDSA using P-256 and SHA-256.

Response

{
  "payment_id": "1232424kw54u1iu12o4141",
  "transaction_ref": 123132123
}
Headers
  • Location: redirect-uri for signing to follow.
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Valid payment request which needs to be signed by Belfius Application
 {
 "error": "Payment has to be signed",
 "error_code": "20010",
 "error_description": "signature_required" 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Request received without a mandatory parameter
 {
 "error": "missing_input",
 "error_code": "10001",
 "error_description": "Missing required input 'INPUT'. DETAILS OF WHAT IS WRONG." 
}
Request received with bad parameters (invalid format) values
 {
 "error": "invalid_input",
 "error_code": "10002",
 "error_description": "Input 'INPUT' is not valid. DETAILS OF WHAT IS WRONG." 
}
Request received with execution-date in past
 {
 "error": "invalid_input",
 "error_code": "10008",
 "error_description": "Execution date must be in future." 
}
Request received with amount<=0
 {
 "error": "invalid_input",
 "error_code": "10009", 
 "error_description": "Amount must be biger than 0." 
}
Request received with currency other than EUR
 {
 "error": "invalid_input",
 "error_code": "10010",
 "error_description": "Currency has to be EUR." 
}
Request received with same account for sender and receiver
 {
 "error": "invalid_input",
 "error_code": "10011",
 "error_description": "Sender and receiver account must not be same." 
}
Request received with commuication where communication_type='STRUCTURED' and communication length is different than 20
 {
 "error": "invalid_input",
 "error_code": "10013",
 "error_description": "Communication must be of exact 20 chars length for STRUCTURED communication." 
}
Request received with Incorrect Order/Beneficiary account OR incorrect structured communication
 {
 "error": "invalid_checkdigit",
 "error_code": "20018",
 "error_description": "Either Order/Beneficiary account is not in correct format OR structured communication is not valid." 
}
Request received with invalid execution-date (weekend e.g.)
 {
 "error": "invalid_input",
 "error_code": "20019",
 "error_description": "Execution date is not valid." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Request received with invalid values for Oauth2 Security related parametes
 {
 "error": "failed_security_validation",
 "error_code": "10003", 
 "error_description": "Validation failed for security related parameters. DETAILS OF WHAT IS WRONG." 
}
Request received with invalid access_token
 {
 "error": "invalid_access_token",
 "error_code": "10006",
 "error_description": "access_token not valid in this scope." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Request received with a Client-ID(TPPID) which is not active
 {
 "error": "blocked_tpp",
 "error_code": "20001", 
 "error_description": "No Active TPP found." 
}
Request received with non-belfius account
 {
 "error": "invalid_account",
 "error_code": "20002", 
 "error_description": "No Account found." 
}
Request received with account 'not consultable with electronic channel'
 {
 "error": "channel_not_permitted",
 "error_code": "20003",
 "error_description": "This account can not be consultated via electronical channel." }
Request received with account 'not allowed for PSD2'
 {
 "error": "account_not_supported",
 "error_code": "20004",
 "error_description": "This account is not allowed for this type of request." 
}
Request received with account for which access has been disabled by provider
 {
 "error": "access_denied",
 "error_code": "20006",
 "error_description": "Access is not ok for this account. Please contact customer support." 
}
Request received with already used payment-id
 {
 "error": "duplicate_payment_id",
 "error_code": "20009", 
 "error_description": "Duplicate payment-id." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Request received with invalid version in Accept header
 {
 "error": "resource_not_found",
 "error_code": "10004",
 "error_description": "Specific version not found.  Supported versions are [X,..]." 
}
Request received with unsupported HTTP verb
 {
 "error": "resource_not_found",
 "error_code": "10102",
 "error_description": "Requested resource was not found." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Request received with restricted HTTP verbs
 {
 "error": "method_not_allowed",
 "error_code": "10103",
 "error_description": "Requested HTTP method is not allowed for this api." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Request received with invalid type in Accept header
 {
 "error": "unacceptable_media_type",
 "error_code": "10005",
 "error_description": "Server can not return the response In the format mentioned in the request. Supported type is application/vnd.belfius.api+json;." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Request received with unsupported Content-Type Header
 {
 "error": "unsupported_media_type",
 "error_code": "10012",
 "error_description": "Content-Type must be application/json." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Client request exceed the configured Quota limit for the associated Account Plan
 {
 "error": "quota_limit_exceeded",
 "error_code": "10105",
 "error_description": "Quota limit exceed." 
}
Client request exceed the configured Quota limit for the associated API Plan
 {
 "error": "quota_limit_exceeded",
 "error_code": "10106",
 "error_description": "Quota limit exceed." 
}
Client request exceeded the configured rate limit
 {
 "error": "rate_limit_exceeded",
 "error_code": "10107",
 "error_description": "Rate limit exceed." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
SSL certificate error
 {
 "error": "ssl_validation_error",
 "error_code": "10020",
 "error_description": "error during client authentication." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Internal server error
 {
 "error": "internal_server_error",
 "error_code": "20020", 
 "error_description": "Internal error occurred." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Headers
  • Response-ID: Same as Request-ID passed in the request.
Possible responses
ScenarioResponse
Client request falls in the configured 'restrict time period' frame
 {
 "error": "service_unavailable",
 "error_code": "10108",
 "error_description": "Service unavailable, please try after some time." 
}
Client request falls in the configured 'restrict day period' frame
 {
 "error": "service_unavailable",
 "error_code": "10109",
 "error_description": "Service unavailable, please try in 24 hours." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Post /payments/sepa-credit-transfers

Request example

{
  "origin_account": {
    "iban": "BE54063301200997"
  },
  "remote_account": {
    "name": "Marcel Thierry",
    "iban": "BE21063304586543",
    "bic": "BEBBEERR"
  },
  "amount": 100.01,
  "currency": "EUR",
  "communication": "+++333/4444/55555+++",
  "communication_type": "STRUCTURED",
  "execution_date": "2017-05-17",
  "payment_id": "1232424kw54u1iu12o4141"
}

Response example

{
  "payment_id": "1232424kw54u1iu12o4141",
  "transaction_ref": 123132123
}
{
 "error": "Payment has to be signed",
 "error_code": "20010",
 "error_description": "signature_required" 
}
{
 "error": "missing_input",
 "error_code": "10001",
 "error_description": "Missing required input 'INPUT'. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "invalid_input",
 "error_code": "10002",
 "error_description": "Input 'INPUT' is not valid. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "invalid_input",
 "error_code": "10008",
 "error_description": "Execution date must be in future." 
}
{
 "error": "invalid_input",
 "error_code": "10009", 
 "error_description": "Amount must be biger than 0." 
}
{
 "error": "invalid_input",
 "error_code": "10010",
 "error_description": "Currency has to be EUR." 
}
{
 "error": "invalid_input",
 "error_code": "10011",
 "error_description": "Sender and receiver account must not be same." 
}
{
 "error": "invalid_input",
 "error_code": "10013",
 "error_description": "Communication must be of exact 20 chars length for STRUCTURED communication." 
}
{
 "error": "invalid_checkdigit",
 "error_code": "20018",
 "error_description": "Either Order/Beneficiary account is not in correct format OR structured communication is not valid." 
}
{
 "error": "invalid_input",
 "error_code": "20019",
 "error_description": "Execution date is not valid." 
}
{
 "error": "failed_security_validation",
 "error_code": "10003", 
 "error_description": "Validation failed for security related parameters. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "invalid_access_token",
 "error_code": "10006",
 "error_description": "access_token not valid in this scope." 
}
{
 "error": "blocked_tpp",
 "error_code": "20001", 
 "error_description": "No Active TPP found." 
}
{
 "error": "invalid_account",
 "error_code": "20002", 
 "error_description": "No Account found." 
}
{
 "error": "channel_not_permitted",
 "error_code": "20003",
 "error_description": "This account can not be consultated via electronical channel." }
{
 "error": "account_not_supported",
 "error_code": "20004",
 "error_description": "This account is not allowed for this type of request." 
}
{
 "error": "access_denied",
 "error_code": "20006",
 "error_description": "Access is not ok for this account. Please contact customer support." 
}
{
 "error": "duplicate_payment_id",
 "error_code": "20009", 
 "error_description": "Duplicate payment-id." 
}
{
 "error": "resource_not_found",
 "error_code": "10004",
 "error_description": "Specific version not found.  Supported versions are [X,..]." 
}
{
 "error": "resource_not_found",
 "error_code": "10102",
 "error_description": "Requested resource was not found." 
}
{
 "error": "method_not_allowed",
 "error_code": "10103",
 "error_description": "Requested HTTP method is not allowed for this api." 
}
{
 "error": "unacceptable_media_type",
 "error_code": "10005",
 "error_description": "Server can not return the response In the format mentioned in the request. Supported type is application/vnd.belfius.api+json;." 
}
{
 "error": "unsupported_media_type",
 "error_code": "10012",
 "error_description": "Content-Type must be application/json." 
}
{
 "error": "quota_limit_exceeded",
 "error_code": "10105",
 "error_description": "Quota limit exceed." 
}
{
 "error": "quota_limit_exceeded",
 "error_code": "10106",
 "error_description": "Quota limit exceed." 
}
{
 "error": "rate_limit_exceeded",
 "error_code": "10107",
 "error_description": "Rate limit exceed." 
}
{
 "error": "ssl_validation_error",
 "error_code": "10020",
 "error_description": "error during client authentication." 
}
{
 "error": "internal_server_error",
 "error_code": "20020", 
 "error_description": "Internal error occurred." 
}
{
 "error": "service_unavailable",
 "error_code": "10108",
 "error_description": "Service unavailable, please try after some time." 
}
{
 "error": "service_unavailable",
 "error_code": "10109",
 "error_description": "Service unavailable, please try in 24 hours." 
}