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

1 - 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.

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

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).

3 - 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
AIS_VALID_CODE_MULTICURRENCY Valid code to get an access token for the consent CONSENT_ID_MULTICURRENCY

 

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 90 days, the duration of an AIS consent.

4 - 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
5 - 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
6 - 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
AUTHORIZATION_ID_FINALISED To retrieve an authorisation with the status “finalised”
AUTHORIZATION_ID_RECEIVED To retrieve an authorisation with the status “received”
AUTHORIZATION_ID_PSU_IDENTIFIED To retrieve an authorisation with the status “psuIdentified”
AUTHORIZATION_ID_PSU_AUTHENTICATED To retrieve an authorisation with the status “psuAuthenticated”
AUTHORIZATION_ID_SCA_METHOD_SELECTED To retrieve an authorisation with the status “scaMethodSelected”
AUTHORIZATION_ID_STARTED To retrieve a authorisation with the status “started”
AUTHORIZATION_ID_FAILED To retrieve an authorisation with the status “failed”
AUTHORIZATION_ID_EXEMPTED 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
CONSENT_ID_MULTICURRENCY Consent with multi-currency account

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
CONSENT_ID_MULTICURRENCY ACCOUNT_ID_MULTI_CURRENCY_XXX Parent account of a consent with multi-currency account
CONSENT_ID_MULTICURRENCY ACCOUNT_ID_MULTI_CURRENCY_CHILD1 Child account 1 of a consent with multi-currency account
CONSENT_ID_MULTICURRENCY ACCOUNT_ID_MULTI_CURRENCY_CHILD2 Child account 2 of a consent with multi-currency account

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 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
CONSENT_ID_MULTICURRENCY ACCOUNT_ID_MULTI_CURRENCY_XXX Parent account of a consent with multi-currency account
CONSENT_ID_MULTICURRENCY ACCOUNT_ID_MULTI_CURRENCY_CHILD1 Child account 1 of a consent with multi-currency account
CONSENT_ID_MULTICURRENCY ACCOUNT_ID_MULTI_CURRENCY_CHILD2 Child account 2 of a consent with multi-currency account

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 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

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.

PIS payment initiation

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

1 - 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
periodic-payments sepa-credit-transfers

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
periodic-payments sepa-credit-transfers PAYMENT_ID_PERIODIC_PATC_SCT

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": "FR2789590438957952169726310"
   },
    "creditorAccount": {
      "iban": "FR5191497531710377217771433"
   },
    "creditorName": "DBL Inc.",
    "requestedExecutionDate": "2030-01-01"
}

2 - Authorize the payment

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 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:

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).

3 - 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)
ACSP (AcceptedSettlementInProcess)
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)
4 - 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
periodic-payments sepa-credit-transfers PAYMENT_ID_PERIODIC_PATC_SCT



GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{paymentAuthorisationId}
paymentAuthorisationId Description
AUTHORIZATION_ID_FINALISED To retrieve an authorisation with the status “finalised”
AUTHORIZATION_ID_RECEIVED To retrieve an authorisation with the status “received”
AUTHORIZATION_ID_PSU_IDENTIFIED To retrieve an authorisation with the status “psuIdentified”
AUTHORIZATION_ID_PSU_AUTHENTICATED To retrieve an authorisation with the status “psuAuthenticated”
AUTHORIZATION_ID_SCA_METHOD_SELECTED To retrieve an authorisation with the status “scaMethodSelected”
AUTHORIZATION_ID_STARTED To retrieve a authorisation with the status “started”
AUTHORIZATION_ID_FAILED To retrieve an authorisation with the status “failed”
AUTHORIZATION_ID_EXEMPTED To retrieve an authorisation with the status “exempted”
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
periodic-payments sepa-credit-transfers

 

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)
ACSP (AcceptedSettlementInProcess)
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
periodic-payments sepa-credit-transfers PAYMENT_ID_PERIODIC_PATC_SCT
Authorize the cancellation of a payment

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 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:

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).

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
periodic-payments sepa-credit-transfers PAYMENT_ID_PERIODIC_PATC_SCT

 

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

 

paymentAuthorisationId Description
AUTHORIZATION_ID_FINALISED To retrieve an authorisation with the status “finalised”
AUTHORIZATION_ID_RECEIVED To retrieve an authorisation with the status “received”
AUTHORIZATION_ID_PSU_IDENTIFIED To retrieve an authorisation with the status “psuIdentified”
AUTHORIZATION_ID_PSU_AUTHENTICATED To retrieve an authorisation with the status “psuAuthenticated”
AUTHORIZATION_ID_SCA_METHOD_SELECTED To retrieve an authorisation with the status “scaMethodSelected”
AUTHORIZATION_ID_STARTED To retrieve a authorisation with the status “started”
AUTHORIZATION_ID_FAILED To retrieve an authorisation with the status “failed”
AUTHORIZATION_ID_EXEMPTED 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