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.
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.
For more details, please refer to the HowTo Manage Consents for Account Information Service
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:
Use the value “CONSENT_ID_NO_AUTHORIZATION” in the request path to test this API.
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 thepossible 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 thefollowing 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).
In order to access the PSD2 requests you need to get an access token for your application. To get this token youhave 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.
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 |
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 |
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.
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” |
For more details, please refer to the HowTo Access Account Information Services
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.
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 |
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.
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 |
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.
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.
For more details, please refer to the HowTo Initiate a Payment and Manage payments information and status
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 :
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": "FR6010096000303953573683E53" }, "creditorAccount": { "iban": "FR5730003000508771112157D50" }, "creditorName": "DBL Inc.", "requestedExecutionDate": "2030-01-01" }
The difference between the creation of single authorisation process and a multi authorisation process is that the header “TPP-Explicit-Authorisation-Preferred” of this request has to be specifically set to “true”.
No authorisation will be created on the payment and you will have to use the “startAuthorization” link of the response (see following request) to create as many as necessary authorisations in order to perform the multi authorisation process
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 |
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).
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)
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 |
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” |
For more details, please refer to the HowTo Cancel a Payment
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)
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 |
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” |
For more details, please refer to the HowTo Request a Confirmation of Funds
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 |