Description

The sandbox is an 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

In an environment production, you will need to have a valid certificate in order to perform the requests. However, in the sandbox environment this is not the case. The only thing you have to do is to use the value “VALID_CERT” in the “X-Client-Cert-Fingerprint” header of each request. This will allow you the access to perform the requests on the sandbox.

You can also put the value “BLOCKED_CERT” to simulate that the certificate used is blocked.

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

AIS Consent creation
Initiate a consent
POST /berlingroup/v1/consents

There are no particular values to add to test this API in the sandbox environment.

Create an authorization on the consent
POST /berlingroup/v1/consents/{consentId}/authorisations

To create another authorization on the consent you can use the value “VALID_CONSENT_ID” in the request to test this API.

Authorize the AIS consent

To simulate the authorization of an AIS consent, a user interface is used: https://api-sandbox.crelan.be/public/berlingroup/authorize?scope=AIS:VALID_CONSENT_ID&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&response_type=code&code_challenge_method=S256

Using it, here are the different authorize cases that return you a response

 

 Authorize case

 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 authorization

 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

 

Get an AIS access Token
GET /berlingroup/v1/token

In order to access the PSD2 request you need to get an access token for your application.

Here are the different authorization_code that you can use in the “code” header

 

 Code

 Description

 AIS_VALID_CODE

 Valid code to get an access token for the consent “VALID_CONSENT_ID”

 AIS_VALID_CODE_REVOKED_BY_PSU

 Valid code to get an access token for the consent “CONSENT_ID_REVOKED_BY_PSU”

 AIS_VALID_CODE_TERMINATED_BY_TPP

 Valid code to get an access token for the consent “CONSENT_ID_REVOKED_BY_PSU”

 AIS_VALID_CODE_EXPIRED

 Valid code to get an access token for the consent “CONSENT_ID_EXPIRED”

 EXPIRED_CODE

 To test an expired code

 

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": "2f46d606323d42ee98b57988409847bfe3074018bd4e459aa167512637ff1e28510641da94844ccb9de6d3eff433cc0d"

}

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 header of the request:

 

 Key

 Value

 grant_type

 refresh_token

 refresh_token

 4db39597dc674268a7fa253d255c47cec7618d14ebdd433a984a7680ce0b77ad0bd76a3a55e8455b980bf41c833a03ce

 

The refresh token will have a validity of 90 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

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

 CONSENT_ID_ALL_PSD2

 CONSENT_ID_AVAILABLE_ACCOUNTS

 CONSENT_ID_AVAILABLE_ACCOUNTS_WITH_BALANCES

 
Get the consent authorizations and status
GET /berlingroup/v1/consents/{consentId}/authorisations

You can use the value “VALID_CONSENT_ID” ain 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/{consentAuthorizationId}

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

Access the AIS accounts
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

Description

VALID_CONSENT_ID

Valid consent

CONSENT_ID_REVOKED_BY_PSU

Consent revoked by the psu

CONSENT_ID_EXPIRED

Consent expired

CONSENT_ID_TERMINATED_BY_TPP

Consent terminated by the TPP

 

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

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.

For the request parameter, use the “ACCOUNT_ID” value to get a valid response.

 Consent Id

 Description

 VALID_CONSENT_ID

 Valid consent

 CONSENT_ID_REVOKED_BY_PSU

 Consent revoked by the psu

 CONSENT_ID_EXPIRED

 Consent expired

 CONSENT_ID_TERMINATED_BY_TPP

 Consent terminated by the TPP

 

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

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.

For the request parameter, use the “ACCOUNT_ID” value to get a valid response.

Use another value for {accountId} in the request parameter to test that there is no permission on this account for the “VALID_CONSENT_ID” consent.

 Consent Id

 Description

 VALID_CONSENT_ID

 Valid consent

 CONSENT_ID_REVOKED_BY_PSU

 Consent revoked by the psu

 CONSENT_ID_EXPIRED

 Consent expired

 CONSENT_ID_TERMINATED_BY_TPP

 Consent terminated by the TPP

 

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

Retrieve the transactions of an account
GET /berlingroup/v1/accounts/{accountId}/transactions?dateFrom=2017-10-01&bookingStatus=booked

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.

For the request parameter, use the “ACCOUNT_ID” value to get a valid response.

Use another value for {accountId} in the request parameter to test that there is no permission on this account for the “VALID_CONSENT_ID” consent.

 Consent Id

 Description

 VALID_CONSENT_ID

 Valid consent

 CONSENT_ID_REVOKED_BY_PSU

 Consent revoked by the psu

 CONSENT_ID_EXPIRED

 Consent expired

 CONSENT_ID_TERMINATED_BY_TPP

 Consent terminated by the TPP

 

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

PIS payment initiation
Initiate a payment
POST /berlingroup/v1/payments/sepa-credit-transfers
POST /berlingroup/v1/periodic-payments/sepa-credit-transfers
POST /berlingroup/v1/bulk-payments/sepa-credit-transfers

There are no particular values to add to test these APIs in the sandbox environment.

Authorize the payment

To simulate the authorization of a payment, a user interface is used: https://api-sandbox.crelan.be/public/berlingroup/authorize?scope=PIS:PAYMENT_ID_RCVD_SCT&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&response_type=code&code_challenge_method=S256

Using it, here are the different authorize cases that return you a response

 

 Authorize case

 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 authorization

 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

 
Get a PIS access Token
GET /berlingroup/v1/token

In order to access the PSD2 request for the payment you need to get an access token for your application.

Here are the different authorization_code that you can use in the “code” header

 

Code

 Description

PIS_VALID_CODE_ACCP

 Valid code to get an access token for a payment with the status “ACCP”

 PIS_VALID_CODE_ACSC

 Valid code to get an access token for a payment with the status “ACSC”

 PIS_VALID_CODE_ACSP

 Valid code to get an access token for a payment with the status “ACSP”

 PIS_VALID_CODE_ACTC

 Valid code to get an access token for a payment with the status “ACTC”

 PIS_VALID_CODE_ACWC

 Valid code to get an access token for a payment with the status “ACWC”

 PIS_VALID_CODE_ACWP

 Valid code to get an access token for a payment with the status “ACWP”

 PIS_VALID_CODE_RCVD

 Valid code to get an access token for a payment with the status “RCVD”

 PIS_VALID_CODE_PDNG

 Valid code to get an access token for a payment with the status “PDNG”

 PIS_VALID_CODE_RJCT

 Valid code to get an access token for a payment with the status “RJCT”

 PIS_VALID_CODE_CANC

 Valid code to get an access token for a payment with the status “CANC”

 EXPIRED_CODE

 To test an expired code

 

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": "2f46d606323d42ee98b57988409847bfe3074018bd4e459aa167512637ff1e28510641da94844ccb9de6d3eff433cc0d"

}

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

Access a payment
GET /berlingroup/v1/payments/sepa-credit-transfers/{paymentId}
GET /berlingroup/v1/payments/sepa-credit-transfers/{paymentId}/status

Here are the different payment ids that you can use in the URL and in the “Consent-Id” header to test these APIs. You also have to use the access token for the corresponding status.

 

 PaymentId

 Description

 PAYMENT_ID_ACCP

 To access a payment with the status “ACCP”

 PAYMENT_ID_ACSC

 To access a payment with the status “ACSC”

 PAYMENT_ID_ACSP

 To access a payment with the status “ACSP”

 PAYMENT_ID_ACTC

 To access a payment with the status “ACTC”

 PAYMENT_ID_ACWC

 To access a payment with the status “ACWC”

 PAYMENT_ID_ACWP

 To access a payment with the status “ACWP”

 PAYMENT_ID_RCVD

 To access a payment with the status “RCVD”

 PAYMENT_ID_PDNG

 To access a payment with the status “PDNG”

 PAYMENT_ID_RJCT

 To access a payment with the status “RJCT”

 PAYMENT_ID_CANC

 To access a payment with the status “CANC”

 
Cancel a payment
DELETE /berlingroup/v1/payments/{paymentId}
Funds confirmation
POST /berlingroup/v1/funds-confirmations