crelan

Technical update

bank-admin — Mon, 17 Nov 2025 12:55:15 +0000

Technical update bank-admin November 17, 2025

Technical update

Anonymous — Mon, 13 Oct 2025 06:56:17 +0000

Technical update Anonymous (not verified) October 13, 2025

Crelan doc

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

Crelan doc cln-devportal October 10, 2025

13 - Build your authorize URL

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

13 - Build your authorize URL cln-devportal October 10, 2025

Build an authorize URL using the well-known configuration link

On the production and sandbox environments, the "scaOauth" property of a consent creation (with header tppExplicitAuthorizationPreferred = false) or a POST /authorization endpoint is the following:

{ … "_links": { "scaOAuth": { "href": "https://api.crelan.be/berlingroup/.well-known/openid-configuration?authorizationId=31f68ab6-1ce6-4131-a324-3f37d2ca4b02" }, … } }

You have to call this URL and retrieve the “authorization_enpoint” property in the response:

{ "issuer": "https://api.crelan.be", "authorization_endpoint": "https://webapi.crelan.be/public/berlingroup/authorize/31f68ab6-1ce6-4131-a324-3f37d2ca4b02", "token_endpoint": "https://api.crelan.be/berlingroup/v1/token", "userinfo_endpoint": "https://api.crelan.be/berlingroup/v1/accounts", "scopes_supported": [ "account", "payment" ], "response_types_supported": [ "code" ], "grant_types_supported": [ "client_credentials", "authorization_code", "refresh_token" ], "code_challenge_methods_supported": [ "S256" ], "subject_types_supported": [ "public" ] }

With this property, you will be able to build your authorize URL with the following parameters:

URI parameter	Description
scope	This parameter corresponds to the consentId of the consent creation or the paymentId of the payment initiation Examples: AIS:1587559935-bae68c2 PIS:1587561419-bp5b5f2
client_id	This parameter corresponds to your NCA id
state	Dynamic value that you have to set in order to prevent XSRF attacks
redirect_uri	This parameter corresponds to the URI where the OAuth2 server is redirecting the PSU after the authorization. NB : this redirect_uri has to be the same used for the consent creation or payment initiation
code_challenge	This parameter corresponds to PKCE challenge according to cryptographic RFC 7636 which is used to prevent code injection attacks
response_type	Type of the response. This value has to be set to “code”
code_challenge_method	Optional parameter which corresponds to the code verifier transformation method ("S256" or "plain")

Following these instructions your authorize URL should look like this and is now valid to process the authorization of the PSU:

https://webapi.crelan.be/public/berlingroup/authorize/31f68ab6-1ce6-4131-a324-3f37d2ca4b02?scope=AIS:1587559935-bae68c2&client_id=[your_client_Id]&state=test&redirect_uri=[your_redirect_uri]&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&response_type=code&code_challenge_method=S256

This process to build the authorize URL is the same for a payment initiation or a payment cancellation with SCA.

NB : the "redirect_uri" parameter in the URL has to be the same as the "TPP-Redirect-URI" header of the consent creation

12 - Connect to the sandbox or Berlin Group APIs

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

12 - Connect to the sandbox or Berlin Group APIs cln-devportal October 10, 2025

Dedicated interface

On the date of 10/09/19 the National Bank of Belgium (NBB) has granted Crelan an exemption from the contingency mechanism in accordance with article 33(6) of Regulation (EU) 2018/389.

The dedicated interface complies with the relevant PSD2 requirements, the RTS on SCA & CSC and the EBA Guidelines.

This means that from 10/09/19 TPPs should only use the dedicated interfaces to obtain the information made accessible by PSD2.

Description

The communication between the TPP and the Bank (Sandbox or Berlin Group APIs) is always secured by using a TLS-connection Mutual authentication using TLS version 1.2 which is initiated by the TPP.

The TLS-connection has to be established always including client (i.e. TPP) authentication.

For this authentication the TPP has to use a qualified certificate for website authentication (QWAC) which has to be issued by a qualified trust service provider according to the eIDAS regulation.

The content of the certificate has to be compliant with the requirements of the EBA-RTS and follow the ETSI TS 119 495 V1.2.1 (2018-11) technical specification.

During the first connection setup, the TPP will be automatically onboarded and registered (enrolled) in the bank database. However, for security purpose, the bank requires the client certificate to be presented within each request.

Following the EBA clarification 07/06/2019, it's now possible to test the Sandbox using a test certificate. The only restriction is that the certificate used to establish the SSL MA must follow the QWAC format for PSD2, according to ETSI TS 119 495 V1.2.1 (2018-11)

For the Berlin Group APIs, the QWAC certificate has to be issued from a production CA.

Test the connection to the sandbox

Make sure that your QWAC configuration is correct by testing the following endpoint on the sandbox (no headers are necessary)

GET /berlingroup/actuator/info

11 - Monitor performance & availability of our APIs

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

11 - Monitor performance & availability of our APIs cln-devportal October 10, 2025

Statistics

As a TPP you may want to see various information and statistics about our APIs. If this is the case, you can get this information by going to the following link:
https://www.crelan.be/nl/business/artikel/statistics

You will be able to see daily statistics on a quarterly basis on the availability and performance of our APIs.

10 - Contact our support team

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

10 - Contact our support team cln-devportal October 10, 2025

Contact our Support Team

As a TPP if you face any problems using either our Sandbox or Production APIs you can contact us by using the dedicated support email : psd2@crelan.be

Please try to give us the full context of your request :

TPP Name,
TPP Registration Number,
Date and Time of the issue,
Service : AIS, PIS, FCS,
Endpoint,
Error message, error code, screenshot,
Information about concerned version by using one of the following URLs.
A valid QWAC Certificate for PSD2 is required in order to access these URLs.
The certificate is mandatory, otherwise you will get an error :
- Sandbox APIs
- Production APIs

Our support team will answer you as soon as possible.

09 - Use our Sandbox Dataset

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

09 - Use our Sandbox Dataset cln-devportal October 10, 2025

Description

The sandbox is a mocked environment which allows you to test your application. This environment simulates API responses of the requests described in API page of this developer portal.

To get a response the request has to match certain headers, path and query parameters with specific values described below. Any deviation in these parameters may return in an error code.

The endpoints used in the sandbox environment are identical as those used in production.

Before starting

You will need to have a valid QWAC Certificate for PSD2 in order to perform the requests on the sandbox. This certificate is mandatory; otherwise you will get an error. The sandbox is freely accessible and you don't need to fulfil an enrolment process to use it

All the specified values to use for the requests will be described in the next paragraphs.

AIS Consent creation

For more details, please refer to the HowTo Manage Consents for Account Information Service

Initiate a consent (Single SCA)

POST /berlingroup/v1/consents

You can create a consent which will create implicitly an authorisation on this consent by setting the header “TPP-Explicit-Authorisation-Preferred” of this request to “false”. In this case, the creation of another authorisation on the consent will be forbidden and you will just have to authorise the consent using the link in the response.

Use the value “VALID_CONSENT_ID” in the request path to test this API.

Here is an example of a body that you can use to test the request:

{
  "access": {
    "allPsd2": "allAccounts"
  },
  "recurringIndicator": true,
  "frequencyPerDay": 4,
  "combinedServiceIndicator": false,
  "validUntil": "2030-12-12"
}

If the header “TPP-Explicit-Authorisation-Preferred” is set to true you will have to create manually an authorisation on the consent with the following request in order get the authorize link:

POST /berlingroup/v1/consents/{consentId}/authorisations

Use the value “CONSENT_ID_NO_AUTHORIZATION” in the request path to test this API.

Authorize the AIS consent

The authorisation workflow implements the BerlinGroup redirect scenario using OAuth2 SCA Protocol.

In order to test this redirect approach, the sandbox provides a graphical user interface in order to simulate all the possible SCA scenarios (Login fails, timeout, SCA rejected…) that are listed below:

SCA scenario	Description
LOGIN_CANCEL	If the login phase was cancelled by the PSU
LOGIN_TIMEOUT	If the login phase encountered a timeout
LOGIN_OTHER_ERROR	If another error occurred during the login phase
LOGIN_REQUEST_REJECTED	If the login phase was rejected
BAD_PASSWORD_LOGIN	If an error occurred during the login phase with a bad password
UNKNOWN_LOGIN	If an error occurred during the login phase with an unknown login
SCA_OK	To get a successful authorisation
SCA_EXEMPTED	If the SCA phase was exempted
SCA_CANCEL	If the SCA phase was cancelled by the PSU
SCA_TIMEOUT	If the SCA phase encountered a timeout
SCA_OTHER_ERROR	If another error occurred during the SCA phase
SCA_NOK	If the SCA phase did not succeed
SCA_REQUEST_REJECTED	If the SCA phase was rejected
SCA_INTERNAL_ERROR	If an internal error occurred

To access this graphical user interface you have to build your authorisation URI using the scaOAuth URL received in the response of the consent initialisation with the following parameters:

URI parameter	Sandbox value	Comments
scope	AIS:VALID_CONSENT_ID	Must be set to this value on the Sandbox. On the production API, Must be set to this the consentId returned by the consent initialisation
client_id	VALID_CLIENT_ID	Must be set to this value on the Sandbox. On Production API, you must provide your NCA id
state	Any value	On Production API, this is a dynamical value that you have to set in order to prevent XSRF attacks
redirect_uri	Any URI value	On Production API, this corresponds to the URI where the OAuth2 server is redirecting the PSU after the authorization
code_challenge	Any value	On Production API, this corresponds to PKCE challenge according to cryptographic RFC 7636 (https://tools.ietf.org/html/rfc7636) and is used to prevent code injection attacks
response_type	code	Must be set to this value on the Sandbox and on Production API
code_challenge_method	S256	On Production API this parameter is optionnal and corresponds to the code verifier transformation method ("S256" or "plain")

Following these instructions, you should build the following URI for the sandbox:

https://webapi-sandbox.crelan.be/public/berlingroup/authorize/11111111-1111-1111-1111-111111111111?scope=AIS:VALID_CONSENT_ID&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&response_type=code&code_challenge_method=S256

This URI will redirect on a mocked page on which you can test the different redirect scenarios of the authorisation flow. All user flow will display an information page before redirecting the PSU to the redirect_uri (HTTP 302 response).

Error management: In order to help TPPs with the errors received through the redirect_uri, Crelan provide more information in the redirect_uri with the properties "psuErrorMessageKey" and "tppErrorTextMessage" in order to better understand the origin of the error. You can test on the sandbox by cliquing on the "SCA Error Cases" buttons as examples.

Get an AIS access Token

POST /berlingroup/v1/token

In order to access the PSD2 requests you need to get an access token for your application. To get this token you have to exchange an authorization_code with a valid token. This authorization_code is found in the 302 response of a valid authorisation.

First of all, you have to use for this request a body encoded as x-www-form-urlencoded.

Here are the specific keys to use for the body of this request: (cf. API /token in API section)

"authorization_code" as value for the "grant_type" parameter
"VALID_CLIENT_ID" as value for the "client_id" parameter
"Any value" as value for the "code_verifier" parameter (On production environment, you have to use the code_verifier of code_challenge provided in the authorize URL)
the following values for the "code" parameter:

Code	Description
AIS_VALID_CODE	Valid code to get an access token for the consent VALID_CONSENT_ID
AIS_VALID_CODE_TRANSACTION_90D_KO	Valid code to get an access token for the consent CONSENT_ID_TRANSACTION_90D_KO. This consent is to used in order to get the error of the access right to transactions older than 90 days

The response to this API comes in the form of a JSON object with the following structure:

{
  "access_token": "4db39597dc674268a7fa253d255c47cec7618d14ebdd433a984a7680ce0b77ad0bd76a3a55e8455b980bf41c833a03ce",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "e3da5c9922a34d6e8fa0fa4b780acc2c1ad3a05d485f43f08580250d26a1782b0544973a64204185a9257ca07143c0bb",
  "scope": "AIS:VALID_CONSENT_ID"
}

This will be the access that has a limited time validity that you have to use for the future request.

According to Oauth2 specification, you can exchange this access token for a refresh token still using the /Token API but with a “refresh_token” as grant type in the body of the request:

Parameter	Value
grant_type	refresh_token
refresh_token	The refresh token that you just got with the /token API
client_id	VALID_CLIENT_ID

The refresh token will have a validity of 180 days, the duration of an AIS consent.

Access the consent

GET/berlingroup/v1/consents/{consentId}

GET/berlingroup/v1/consents/{consentId}/status

Here are the different consent ids that you can use to test these APIs.

Consent Id	Description
VALID_CONSENT_ID	To retrieve a consent with the status “Valid” and a preselected scope
CONSENT_ID_REVOKED_BY_PSU	To retrieve a consent with the status “revokedByPsu”
CONSENT_ID_EXPIRED	To retrieve a consent with the status “expired”
CONSENT_ID_REJECTED	To retrieve a consent with the status “rejected”
CONSENT_ID_TERMINATED_BY_TPP	To retrieve a consent with the status “terminatedByTpp”
CONSENT_ID_RECEIVED	To retrieve a consent with the status “received”
CONSENT_ID_ALL_PSD2	To retrieve a consent with the status “Valid” and a “allPsd2” scope
CONSENT_ID_AVAILABLE_ACCOUNTS	To retrieve a consent with the status “Valid” and a “availableAccounts” scope
CONSENT_ID_AVAILABLE_ACCOUNTS_WITH_BALANCES	To retrieve a consent with the status “Valid” and a “availableAccountsWithBalances” scope

Delete a consent

DELETE /berlingroup/v1/consents/{consentId}

Here are the different consent ids that you can use to test this API.

Consent Id
VALID_CONSENT_ID
CONSENT_ID_REVOKED_BY_PSU
CONSENT_ID_EXPIRED
CONSENT_ID_REJECTED
CONSENT_ID_TERMINATED_BY_TPP
CONSENT_ID_RECEIVED

Get the consent authorisations and status

GET /berlingroup/v1/consents/{consentId}/authorisations

This request retrieves the list of the authorisations of the consent.

You can use the value “VALID_CONSENT_ID” in the request to test this API. If you use another value, the consent will be considered as not found.

GET /berlingroup/v1/consents/{consentId}/authorisations/{consentAuthorisationId}

You can use the value “VALID_CONSENT_ID” and a value for the “consentAuthorisationId” in the request path to test this API. If you use another value, the consent will be considered as not found.

consentAuthorisationId	Description
11111111-1111-1111-1111-111111111111	To retrieve an authorisation with the status “finalised”
22222222-2222-2222-2222-222222222222	To retrieve an authorisation with the status “received”
33333333-3333-3333-3333-333333333333	To retrieve an authorisation with the status “psuIdentified”
44444444-4444-4444-4444-444444444444	To retrieve an authorisation with the status “psuAuthenticated”
55555555-5555-5555-5555-555555555555	To retrieve an authorisation with the status “scaMethodSelected”
66666666-6666-6666-6666-666666666666	To retrieve a authorisation with the status “started”
77777777-7777-7777-7777-777777777777	To retrieve an authorisation with the status “failed”
88888888-8888-8888-8888-888888888888	To retrieve an authorisation with the status “exempted”

Access the AIS accounts

For more details, please refer to the HowTo Access Account Information Services

Retrieve all accounts

GET /berlingroup/v1/accounts

Here are the different consent ids that you can use to in the “Consent-Id” header to test this API.

You also have to use the access token for the corresponding status.

Consent-Id (header)	Description
VALID_CONSENT_ID	Valid consent

You have a limited access of 4 times per day to this API. You have to include the IP address from which the PSU accesses the TPP service in the PSU-IP-Address header in order not to apply the restriction.

Retrieve the detail of an account

GET /berlingroup/v1/accounts/{accountId}

Here are the different consent ids that you can use to in the “Consent-Id” header to test this API.

You also have to use the access token for the corresponding status.

Consent-Id (header)	Account Id (request parameter)	Description
VALID_CONSENT_ID	ACCOUNT_ID	Account of a valid consent
VALID_CONSENT_ID	Any unknown account	No permission on this account

Retrieve the balances of an account

GET /berlingroup/v1/accounts/{accountId}/balances

Here are the different consent ids that you can use to in the “Consent-Id” header to test this API.

You also have to use the access token for the corresponding status.

Consent-Id (header)	Account Id (request parameter)	Description
VALID_CONSENT_ID	ACCOUNT_ID	Account of a valid consent
VALID_CONSENT_ID	Any unknown account	No permission on this account

Retrieve the transactions of an account

GET /berlingroup/v1/accounts/{accountId}/transactions?dateFrom=2019-02-01&bookingStatus=booked

Here are the different parameters that you can use to test this API.

You also have to use the access token for the corresponding consent.

Consent-Id (header)	Account Id (request parameter)	Description
VALID_CONSENT_ID	ACCOUNT_ID	Account of a valid consent
VALID_CONSENT_ID	Any unknown account	No permission on this account
CONSENT_ID_TRANSACTION_90D_KO	ACCOUNT_ID	Account where the access right to transactions older than 90 days is expired

PIS payment initiation

For more details, please refer to the HowTo Initiate a Payment and Manage payments information and status

Initiate a payment (Single SCA)

POST /berlingroup/v1/{payment-service}/{payment-product}

Here are the different combinations that you can use in the URL of this request:

Payment service	Payment product
payments	sepa-credit-transfers
	instant-sepa-credit-transfers
	cross-border-payments
periodic-payments	sepa-credit-transfers
	instant-sepa-credit-transfers
	cross-border-payments
bulk-payments	sepa-credit-transfers
	instant-sepa-credit-transfers
	cross-border-payments

You can create a payment which will create implicitly an authorisation on this payment by setting the header “TPP-Explicit-Authorisation-Preferred” of this request to “false”. In this case, the creation of another authorisation on the payment will be forbidden and you will just have to authorise the payment using the link in the response.

If this header is set to true you will have to create manually an authorisation on the payment with the following request :

POST /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/authorisations

Use the values below in the request path to test this API:

Payment service	Payment product	Payment Id
payments	sepa-credit-transfers	PAYMENT_ID_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_PATC_ISCT
periodic-payments	sepa-credit-transfers	PAYMENT_ID_PERIODIC_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_PERIODIC_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_PERIODIC_PATC_ISCT
bulk-payments	sepa-credit-transfers	PAYMENT_ID_BULK_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_BULK_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_BULK_PATC_ISCT

Here is an example of a body that you can use to test the request (single payment sepa credit transfers):

{
  "instructedAmount": {
    "currency": "EUR",
    "amount": "42"
  },
  "debtorAccount": {
    "iban": "FR6010096000303953573683E53"
  },
  "creditorAccount": {
    "iban": "FR5730003000508771112157D50"
  },
  "creditorName": "DBL Inc.",
  "requestedExecutionDate": "2030-01-01"
}

Authorize the payment

The authorisation workflow implements the BerlinGroup redirect scenario using OAuth2 SCA Protocol.

SCA scenario	Description
LOGIN_CANCEL	If the login phase was cancelled by the PSU
LOGIN_TIMEOUT	If the login phase encountered a timeout
LOGIN_OTHER_ERROR	If another error occurred during the login phase
LOGIN_REQUEST_REJECTED	If the login phase was rejected
BAD_PASSWORD_LOGIN	If an error occurred during the login phase with a bad password
UNKNOWN_LOGIN	If an error occurred during the login phase with an unknown login
SCA_OK	To get a successful authorisation
SCA_EXEMPTED	If the SCA phase was exempted
SCA_CANCEL	If the SCA phase was cancelled by the PSU
SCA_TIMEOUT	If the SCA phase encountered a timeout
SCA_OTHER_ERROR	If another error occurred during the SCA phase
SCA_NOK	If the SCA phase did not succeed
SCA_REQUEST_REJECTED	If the SCA phase was rejected
SCA_INTERNAL_ERROR	If an internal error occurred

To access this graphical user interface you have to build your authorisation URI using the scaOAuth URL received in the response of the payment initialisation with the following parameters:

URI parameter	Sandbox value	Comments
scope	PIS:PAYMENT_ID_RCVD_SCT	Must be set to this value on the Sandbox. On the production API, Must be set to this the consentId returned by the consent initialisation
client_id	VALID_CLIENT_ID	Must be set to this value on the Sandbox. On Production API, you must provide your NCA id
state	Any value	On Production API, this is a dynamical value that you have to set in order to prevent XSRF attacks
redirect_uri	Any URI value	On Production API, this corresponds to the URI where the OAuth2 server is redirecting the PSU after the authorization
code_challenge	Any value	On Production API, this corresponds to PKCE challenge according to cryptographic RFC 7636 (https://tools.ietf.org/html/rfc7636) and is used to prevent code injection attacks
response_type	code	Must be set to this value on the Sandbox and on Production API
code_challenge_method	S256	On Production API this parameter is optionnal and corresponds to the code verifier transformation method ("S256" or "plain")

Following these instructions, you should build the following URI for the sandbox:

https://webapi-sandbox.crelan.be/public/berlingroup/authorize/11111111-1111-1111-1111-111111111111?scope=PIS:PAYMENT_ID_RCVD_SCT&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&response_type=code&code_challenge_method=S256

Access a payment

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/status

The different payment ids to use in the URL and in the “Consent-Id” header of these requests have this structure:

PAYMENT_ID_<payment service>_<payment status>_<payment product>

Payment service	Payment status	Payment product
∅ (payment)	ACCP (AcceptedCustomerProfile)	SCT (sepa credit transfer)
PERIODIC (periodic payment)	ACSC (AcceptedSettlementCompleted)	ISCT (instant sepa credit transfert)
BULK (bulk payment)	ACSP (AcceptedSettlementInProcess)	CBP (cross border payment)
	ACTC (AcceptedTechnicalValidation)
	ACWC (AcceptedWithChange)
	ACWP (AcceptedWithoutPosting)
	RCVD (Received)
	PDNG (Pending)
	RJCT (Rejected)
	CANC (Cancelled)
	PATC (PartiallyAcceptedTechnicalCorrect)

Examples:

PAYMENT_ID_RCVD_SCT (« payment – status received - sepa credit transfert)
PAYMENT_ID_PERIODIC_PDNG_SCT (« periodic payment – status pending - sepa credit transfert)
PAYMENT_ID_BULK_RJCT_SCT (« bulk payment – status rejected – sepa credit transfert)

Get the payment authorisations and status

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/authorisations

This request retrieves the list of the authorisations of the payment.

You can use the values below to test this API:

Payment service	Payment product	Payment Id
payments	sepa-credit-transfers	PAYMENT_ID_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_PATC_ISCT
periodic-payments	sepa-credit-transfers	PAYMENT_ID_PERIODIC_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_PERIODIC_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_PERIODIC_PATC_ISCT
bulk-payments	sepa-credit-transfers	PAYMENT_ID_BULK_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_BULK_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_BULK_PATC_ISCT

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{paymentAuthorisationId}

paymentAuthorisationId	Description
11111111-1111-1111-1111-111111111111	To retrieve an authorisation with the status “finalised”
22222222-2222-2222-2222-222222222222	To retrieve an authorisation with the status “received”
33333333-3333-3333-3333-333333333333	To retrieve an authorisation with the status “psuIdentified”
44444444-4444-4444-4444-444444444444	To retrieve an authorisation with the status “psuAuthenticated”
55555555-5555-5555-5555-555555555555	To retrieve an authorisation with the status “scaMethodSelected”
66666666-6666-6666-6666-666666666666	To retrieve a authorisation with the status “started”
77777777-7777-7777-7777-777777777777	To retrieve an authorisation with the status “failed”
88888888-8888-8888-8888-888888888888	To retrieve an authorisation with the status “exempted”

Payment status notification Callback (Instant Payment only)

Payment status notification is currently only supported for Instant Payment. To simulate a Payment Status Notification Event you can call the endpoint

POST {{SANDBOX_URL}}/internal/berlingroup/authorization/v1/tpp/notify

In the body request, you need to provide the following information :

Payment Id : Payment Id of the notification
Notification URL: URL where the TPP wants to receive the notification
Payment status: Payment Status of the event. This can be change to simulate different payment status

Example:


                { 
"paymentId": "12345-23454-123123", 

                "tppNotificationUri": "https://notifications.tppurl.com/",

                "status": "ACCP" 

                }

The Sandbox will then trigger the following callback


                    POST https://notifications.tppurl.com/

                    Body request

                    {
 
                        "payment-ID": "12345-23454-123123", 

                        "transactionStatus": "ACSP" 

                    }

Cancel a payment

For more details, please refer to the HowTo Cancel a Payment

DELETE /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}

Here are the different combinations that you can use in the URL of this request:

Payment service	Payment product
payments	sepa-credit-transfers
payments	cross-border-payments
periodic-payments	sepa-credit-transfers
periodic-payments	cross-border-payments

For the payment Id parameter, here is its structure:

PAYMENT_ID_<payment service>_<payment status>_<payment product>

Payment service	Payment status	Payment product
∅ (payment)	ACCP (AcceptedCustomerProfile)	SCT (sepa credit transfer)
PERIODIC (periodic payment)	ACSC (AcceptedSettlementCompleted)	ISCT (instant sepa credit transfert)
BULK (bulk payment)	ACSP (AcceptedSettlementInProcess)	CBP (cross border payment)
	ACTC (AcceptedTechnicalValidation)
	ACWC (AcceptedWithChange)
	ACWP (AcceptedWithoutPosting)
	RCVD (Received)
	PDNG (Pending)
	RJCT (Rejected)
	CANC (Cancelled)
	PATC (PartiallyAcceptedTechnicalCorrect)

Examples:

PAYMENT_ID_RCVD_SCT (« payment – status received - sepa credit transfert)
PAYMENT_ID_PERIODIC_PDNG_SCT (« periodic payment – status pending - sepa credit transfert)

Cancel a payment with SCA

In case of the cancellation of a payment with SCA, just after deleting the payment with the /DELETE API, you have to call the request below in order to create an authorisation to cancel the payment and get the authorisation link.

POST /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations

Use the values below in the request path to test this API:

Payment service	Payment product	Payment Id
payments	sepa-credit-transfers	PAYMENT_ID_PATC_SCT
payments	cross-border-credit-transfers	PAYMENT_ID_PATC_CBP
periodic-payments	sepa-credit-transfers	PAYMENT_ID_PERIODIC_PATC_SCT
periodic-payments	cross-border-credit-transfers	PAYMENT_ID_PERIODIC_PATC_CBP

Authorize the cancellation of a payment

The authorisation workflow implements the BerlinGroup redirect scenario using OAuth2 SCA Protocol.

SCA scenario	Description
LOGIN_CANCEL	If the login phase was cancelled by the PSU
LOGIN_TIMEOUT	If the login phase encountered a timeout
LOGIN_OTHER_ERROR	If another error occurred during the login phase
LOGIN_REQUEST_REJECTED	If the login phase was rejected
BAD_PASSWORD_LOGIN	If an error occurred during the login phase with a bad password
UNKNOWN_LOGIN	If an error occurred during the login phase with an unknown login
SCA_OK	To get a successful authorisation
SCA_EXEMPTED	If the SCA phase was exempted
SCA_CANCEL	If the SCA phase was cancelled by the PSU
SCA_TIMEOUT	If the SCA phase encountered a timeout
SCA_OTHER_ERROR	If another error occurred during the SCA phase
SCA_NOK	If the SCA phase did not succeed
SCA_REQUEST_REJECTED	If the SCA phase was rejected
SCA_INTERNAL_ERROR	If an internal error occurred

To access this graphical user interface you have to build your authorisation URI using the scaOAuth URL received in the response of the cancellation authorisation request with the following parameters:

URI parameter	Sandbox value	Comments
scope	PIS:PAYMENT_ID_PDNG_SCT	Must be set to this value on the Sandbox. On the production API, Must be set to this the consentId returned by the consent initialisation
client_id	VALID_CLIENT_ID	Must be set to this value on the Sandbox. On Production API, you must provide your NCA id
state	Any value	On Production API, this is a dynamical value that you have to set in order to prevent XSRF attacks
redirect_uri	Any URI value	On Production API, this corresponds to the URI where the OAuth2 server is redirecting the PSU after the authorization
code_challenge	Any value	On Production API, this corresponds to PKCE challenge according to cryptographic RFC 7636 (https://tools.ietf.org/html/rfc7636) and is used to prevent code injection attacks
response_type	code	Must be set to this value on the Sandbox and on Production API
code_challenge_method	S256	On Production API this parameter is optionnal and corresponds to the code verifier transformation method ("S256" or "plain")

Following these instructions, you should build the following URI for the sandbox:

The sandbox offers the possibility to simulate the different authentications scenarios (see the table below) using the following page:

https://webapi-sandbox.crelan.be/public/berlingroup/cancel/authorize/99999999-9999-9999-9999-999999999999?scope=PIS:PAYMENT_ID_PDNG_SCT&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&response_type=code&code_challenge_method=S256

Get the payment cancellation authorisations and status

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations

This request retrieves the list of the authorisations of the cancellation of a payment.

You can use the values below to test this API:

Payment service	Payment product	Payment Id
payments	sepa-credit-transfers	PAYMENT_ID_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_PATC_ISCT
periodic-payments	sepa-credit-transfers	PAYMENT_ID_PERIODIC_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_PERIODIC_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_PERIODIC_PATC_ISCT
bulk-payments	sepa-credit-transfers	PAYMENT_ID_BULK_PATC_SCT
	cross-border-credit-transfers	PAYMENT_ID_BULK_PATC_CBP
	instant-sepa-credit-transfers	PAYMENT_ID_BULK_PATC_ISCT

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations/{paymentAuthorisationId}

paymentAuthorisationId	Description
11111111-1111-1111-1111-111111111111	To retrieve an authorisation with the status “finalised”
22222222-2222-2222-2222-222222222222	To retrieve an authorisation with the status “received”
33333333-3333-3333-3333-333333333333	To retrieve an authorisation with the status “psuIdentified”
44444444-4444-4444-4444-444444444444	To retrieve an authorisation with the status “psuAuthenticated”
55555555-5555-5555-5555-555555555555	To retrieve an authorisation with the status “scaMethodSelected”
66666666-6666-6666-6666-666666666666	To retrieve a authorisation with the status “started”
77777777-7777-7777-7777-777777777777	To retrieve an authorisation with the status “failed”
88888888-8888-8888-8888-888888888888	To retrieve an authorisation with the status “exempted”

Funds confirmation

For more details, please refer to the HowTo Request a Confirmation of Funds

POST /berlingroup/v1/funds-confirmations

This request checks if funds are available for an account and an amount.

The values below allow you performing the different scenario cases:

IBAN	Amount on the account	Overdraft of the account	Currency	PIIS Consent existence
FR8230066631856742938741993	150,02	100	EUR	yes

08 - Specific BerlinGroup Implementation

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

08 - Specific BerlinGroup Implementation cln-devportal October 10, 2025

General Information

API base URL: https://api.crelan.be
Authorisation base URL: https://webapi.crelan.be/public
Sandbox base URL : https://api-sandbox.crelan.be
Sandbox authorisation base URL : https://webapi-sandbox.crelan.be/public
BerlinGroup Conformity : Implementation Guidelines version 1.3
More details on how the APIs work, including sample queries, etc, are available in the Berlin Group's specifications. The above link redirects to the Implementation Guidelines, as well as the Berlin Group specifications in Open API 3.0 format.

TPP Identification Policy

QWAC verification

A valid QWAC Certificate for PSD2 is required to access the Sandbox and Berlin Group API. The following conditions are verified:

The certificate must be valid (the connection date is strictly between the creation date and the expiration date of the certificate)
The certificate must be issued by a QWAC Certificate Authority. The official list of QTSP is available on the eIDAS Trusted List
The certificate should not be revoked

If one of the conditions is not fulfilled, the connection is closed and the TPP received an HTTP 403 response (Access forbidden).

A TPP can provide and use any number of valid certificates as long as the CA properties and organizationIdentifier stay the same. The old certificates are not revoked when a new valid certificate is presented by the TPP and can be kept in use until their expiration date is passed.

General settings

SCA Approach		Supported
Redirect OAuth 2.0 workflow		✔
App redirection using App-to-App redirection based on deep linking workflow		✔
Decoupled workflow		✖
Embedded workflow		✖

Account Information Service

Services		Supported
Support of multiple consents		✖
Support of Signing Baskets		✖
Support of Card Accounts Endpoints		✖
Support display of Account ownerName and ownerNames		✔
Support display of Account psuName		✖
Owner name always delivered without taking into account the consent scope		✖
Support of Trusted Beneficiaries endpoint		✖
Support of Multilevel SCA Approach		✖
Maximum Frequency Per Day Value Supported on Consent Request		4
SCA Validity for a current consent		180 days
SCA Validity for a one-off consent		20 min
Consent establishment Timeout		3 days
Support of parameter withBalance on APIs		✔
Supported Account Reference Identifiers	IBAN	✔
	MaskedPan	✖
	BBAN	✖
Consent scope	Dedicated consent (List of accounts)	✔
	Dedicated consent - Support of ownerName in additionalInformation property	✔
	Dedicated consent - Support of trustedBeneficiaries in additionalInformation property	✖
	Global consent - availableAccounts = allAccounts	✔
	Global consent - availableAccountsWithBalance= allAccounts	✔
	Global consent - allPsd2= allAccounts	✔
	Global consent - availableAccounts = allAccountsWithOwnerName	✔
	Global consent - availableAccountsWithBalance= allAccountsWithOwnerName	✔
	Global consent - allPsd2= allAccountsWithOwnerName	✔
Supported Access for MultiCurrency Accounts		✖
Multicurrency level	Aggregation level	✖
	Sub-account level	✖
	Aggregation & sub-account level	✖
Balance Type	closingBooked	✖
	expected	✖
	openingBooked	✖
	interimAvailable	✖
	interimBooked	✔
	forwardAvailable	✖
Supported Transactions Query Parameters	bookingStatus = booked	✔
	bookingStatus = pending	✖
	bookingStatus = both	✖
	bookingStatus = all to request all types of transactions (pending, booked and information) at once	✖
	dateFrom	✔
	dateTo	✔
	entryReferenceFrom	✖
	deltaList	✖
	Support of Standing orders endpoint (bookingStatus=information)	✖
Supported optional transaction information (Standing Orders)	debtorName	✖
	instructionIdentification	✖
	remittanceInformationUnstructuredArray	✖
	remittanceInformationStructuredArray	✖
	creditorAgent	✖
	debtorAgent	✖
	balanceAfterTransaction	✖

Payment Initiation Service

Services		Supported
Support of Signing Baskets		✖
Payment initiation Timeout		2 days
Support of PIS without IBAN - Retrieval of debtor accounts with AIS flow		✔
Selection of debtor account on CBS pages when payment submission without IBAN		✖
Funds Availability on Payment Status Information (implicit FCS over PIS)		✔
Support of TPP-Rejection-NoFunds-Preferred Header		✖
Support payment status notification (instant payment only)		✖
Mandatory Authorisation on Payment Cancellation		✔
Supported Access for MultiCurrency Accounts		✖
Multicurrency level	Aggregation level	✖
	Sub-account level	✖
	Aggregation & sub-account level	✖
Support display of ownerNames in payment status request		✖
Support display of psuName in payment status request and SCA status request		✖

Support of SEPA credit transfers
Payment services	Single payments	Periodic Payments	Bulk Payments
Support	✔	✔	✔
Cancel	✔	✔	✖
Support of Future Dated Payments	✖
Multilevel SCA Approach	✖
Optional properties management on payment	Single payments	Periodic Payments	Bulk Payments
debtorId	✖	✖	✖
debtorName	✖	✖	✖
ultimateDebtor	✖	✖	✖
currencyOfTransfer	✔	✔	✔
instructionIdentification	✖	✖	✖
exchangeRateInformation	✖	✖	✖
creditorAgentName	✖	✖	✖
creditorId	✖	✖	✖
creditorNameAndAddress	✖	✖	✖
ultimateCreditor	✖	✖	✖
purposeCode	✖	✖	✖
chargeBearer	✖	✖	✖
remittanceInformationUnstructured	✔	✔	✔
remittanceInformationUnstructuredArray	✖	✖	✖
remittanceInformationStructured	✔	✔	✔
remittanceInformationStructuredArray	✖	✖	✖
paymentInformationId	✖	✖	✖
requestedExecutionDate	✔	✔	✔
requestedExecutionTime			✖

Support of crossborder payment
Payment services	Single payments	Periodic Payments	Bulk Payments
Support	✔	✖	✖
Cancel	✔	✖	✖
Support of Future Dated Payments	✖
Multilevel SCA Approach	✖
Optional properties management on payment	Single payments	Periodic Payments	Bulk Payments
debtorId	✖	✖	✖
debtorName	✖	✖	✖
ultimateDebtor	✖	✖	✖
currencyOfTransfer	✔	✖	✖
instructionIdentification	✖	✖	✖
exchangeRateInformation	✔	✖	✖
creditorAgentName	✔	✖	✖
creditorId	✖	✖	✖
creditorNameAndAddress	✖	✖	✖
ultimateCreditor	✖	✖	✖
purposeCode	✖	✖	✖
chargeBearer	✔	✖	✖
remittanceInformationUnstructured	✔	✖	✖
remittanceInformationUnstructuredArray	✖	✖	✖
remittanceInformationStructured	✖	✖	✖
remittanceInformationStructuredArray	✖	✖	✖
paymentInformationId	✖	✖	✖
requestedExecutionDate	✔	✖	✔
requestedExecutionTime			✖
Identification management for crossborder payment			Supported
IBAN			✖
IBAN + BIC + Country Code			✔
IBAN + BIC			✔
BBAN + BIC + Country Code			✖
BBAN + BIC			✖

Support of Instant SEPA credit transfers
Payment services	Single payments	Periodic Payments	Bulk Payments
Support	✔	✔	✔
Cancel	✖	✖	✖
Support of Future Dated Payments	✖
Multilevel SCA Approach	✖
Optional properties management on payment	Single payments	Periodic Payments	Bulk Payments
debtorId	✖	✖	✖
debtorName	✖	✖	✖
ultimateDebtor	✖	✖	✖
currencyOfTransfer	✔	✖	✖
instructionIdentification	✖	✖	✖
exchangeRateInformation	✖	✖	✖
creditorAgentName	✖	✖	✖
creditorId	✖	✖	✖
creditorNameAndAddress	✖	✖	✖
ultimateCreditor	✖	✖	✖
purposeCode	✖	✖	✖
chargeBearer	✖	✖	✖
remittanceInformationUnstructured	✔	✔	✔
remittanceInformationUnstructuredArray	✖	✖	✖
remittanceInformationStructured	✔	✖	✖
remittanceInformationStructuredArray	✖	✖	✖
paymentInformationId	✖	✖	✖
requestedExecutionDate	✔	✔	✔
requestedExecutionTime			✖

Support of Target2 payment
Payment services	Single payments	Periodic Payments	Bulk Payments
Support	✖	✖	✖
Cancel	✖	✖	✖
Support of Future Dated Payments	✖
Multilevel SCA Approach	✖
Optional properties management on payment	Single payments	Periodic Payments	Bulk Payments
debtorId	✖	✖	✖
debtorName	✖	✖	✖
ultimateDebtor	✖	✖	✖
currencyOfTransfer	✖	✖	✖
instructionIdentification	✖	✖	✖
exchangeRateInformation	✖	✖	✖
creditorAgentName	✖	✖	✖
creditorId	✖	✖	✖
creditorNameAndAddress	✖	✖	✖
ultimateCreditor	✖	✖	✖
purposeCode	✖	✖	✖
chargeBearer	✖	✖	✖
remittanceInformationUnstructured	✖	✖	✖
remittanceInformationUnstructuredArray	✖	✖	✖
remittanceInformationStructured	✖	✖	✖
remittanceInformationStructuredArray	✖	✖	✖
paymentInformationId	✖	✖	✖
requestedExecutionDate	✖	✖	✖
requestedExecutionTime			✖

Periodic payments options		Supported
Support of Day Of Execution		✔
Supported Execution Rules	Following	✔
Supported Execution Rules	Preceding	✖
Supported Frequencies	Daily	✔
Weekly	✔
EveryTwoWeeks	✖
Monthly	✔
EveryTwoMonths	✔
Quarterly	✔
SemiAnnual	✔
Annual	✔
MonthlyVariable	✔

Funds Confirmation Service

Services		Supported
Support of Funds Confirmation Endpoints		✔
Creation of Funds Confirmation consent by TPP		✖
Support Access for MultiCurrency accounts		✖
Multicurrency level	Aggregation level	✖
	Sub-account level	✖
	Aggregation & sub-account level	✖

07 - Perform a Strong Customer Authentication

cln-devportal — Fri, 10 Oct 2025 16:25:32 +0000

07 - Perform a Strong Customer Authentication cln-devportal October 10, 2025

Description

To carry out its strong authentication on the ASPSP side, the PSU will be redirected from the TPP APP through several pages within the workflow described below.

AIS Signature Screen

Before being redirected to the TPP App, the PSU will access a redirection screen with some context related to the given authorisation. This screen is slightly different for AIS and PIS.

PIS Signature Screen

AIS Redirection Screen

PIS Redirection Screen

App2App

AIS

PIS

crelan

Technical update

Technical update

Crelan doc

13 - Build your authorize URL

Build an authorize URL using the well-known configuration link

12 - Connect to the sandbox or Berlin Group APIs

Description

Test the connection to the sandbox

11 - Monitor performance & availability of our APIs

Statistics

10 - Contact our support team

Contact our Support Team

09 - Use our Sandbox Dataset

Description

Before starting

AIS Consent creation

Access the AIS accounts

PIS payment initiation

Cancel a payment

Funds confirmation

08 - Specific BerlinGroup Implementation

General Information

TPP Identification Policy

General settings

Account Information Service

Payment Initiation Service

Funds Confirmation Service

07 - Perform a Strong Customer Authentication

App2App

Error Management