Sandbox

Introduction

The sandbox allows you to test the APIs with dummy data and accounts.

To be able to use it you have several steps to follow :

  1. Create a developer account or log in
  2. Create an application to obtain an API key
  • The API key identifies the application and is linked to your developer account. The same API key can be used for the sandbox or the production if you have provided all official data (TPP identifier, certificate chain).
  • If you want to use the sandbox and test a mutual TLS connection, you will have to provide a certificate chain. This is not mandatory for the moment.
  • You will have to create an application for each bank hosted by Arkéa
  1. Retrieve access token (see AISP/CBPII sandbox or PISP sandbox descriptions below)
  2. Test the API by requesting the URLs dedicated to the sandbox (a different URL has to be used for the production). See the API documentation for more detail.
  • Crédit Mutuel de Bretagne : https://api-sandbox.cmb.fr
  • Crédit Mutuel du Sud-Ouest : https://api-sandbox.cmso.com
  • Fortuneo : https://api-sandbox.fortuneo.com
  • Max : https://api-sandbox.max.fr
  • Arkéa Banque Privée : https://api-sandbox.arkeabanqueprivee.fr
  • Arkéa Banque Entreprises et Institutionnels : https://api-sandbox.arkea-banque-ei.com
  • Arkéa Banking Services : https://api-sandbox.arkea-banking-services.com
  • BPE : https://api-sandbox.bpe.fr
  • Allianz Banque : https://api-sandbox.allianzbanque.fr

 

AISP/CBPII Sandbox

If you are an AISP, you will be able to test the following endpoints :

  • GET /accounts
  • GET /accounts/{accountResourceId}/balances
  • GET /accounts/{accountResourceId}/transactions
  • GET /end-user-identity
  • GET /trusted-beneficiaries

A CBPII will be able to test the following endpoints :

  • POST /funds-confirmations

Whether you are an AISP or a CBPII, you will need to retrieve an access token to be able to invoke those endpoints. The list of use cases you can deal with is provided at the end of this page.

How to retrieve the access token ?

We follow the OAuth 2.0 Authorization Code Grant as described in RFC 6749. Here is a quick description for the sandbox mode.

Step1 - Retrieve the authorization code by simulating the redirection of the PSU to the authorization application of the bank.

curl -v -X GET 'https://api.arkea.com/psd2-psu-sandbox/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUrl}&scope=aisp&state={state}&psu={accessCode}'

where :

  • {clientId} is the API key of your application
  • {redirectUrl} is the callback URL you have provided in the application description
  • {state} is the state which can be provided by the client in the Authorization Request of the OAuth Authorization Grant (see RFC 6749 for more detail)

    This parameter is not mandatory
  • {accessCode} is the PSU’s access code which identifies the use case you want to test (available use cases are available at the end of this section).

In case of success the response is a 302 formatted as follows

HTTP/1.1 302 Found
Location: {redirectUrl}?code={code}&state={state}

where :

  • {redirectUrl} is the callback URL you have provided in the request
  • {state} is the state you have provided in the request (if any)
  • {code} is the authorization code you will be able to use to get the access token

In case of failure the response is a 302 formatted as follows

HTTP/1.1 302 Found
{redirectUrl}?error=access_denied&code={code}&state={state}

 

Step2 - Get the access token (and refresh-token) from the authorization code. This is done by sending the following request according to the OAuth 2.0 Authorization Code Grant.

curl -v -X POST '{https://api-sandbox.xxx}/oauth-authorizationcode-psd2/token' -d 'client_id={clientId}&grant_type=authorization_code&redirect_uri={redirectUrl}&code={code}'

where :

  • {https://api-sandbox.xxx} is the sandbox host of the bank you want to test (see above)
  • {clientId} is the API key of your application
  • {redirectUrl} is the callback URL you have provided while requesting the authorization code
  • {code} is the authorization code you have retrieved at the previous step

In case of success the response is a 200 formatted as follows

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "access_token":"{accessToken}",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"{refreshToken}"
}

where :

  • {accessToken} is the access token which identifies the PSU and the TPP’s application
  • {refreshToken} is the token which will allow you to retrieve a new access token (see below)

 

Refresh the access token

curl -X POST '{https://api-sandbox.xxx}/oauth-authorizationcode-psd2/token' -d 'grant_type=refresh_token&refresh_token={refreshToken}'

where :

  • {https://api-sandbox.xxx} is the sandbox host of the bank you want to test (see above)
  • {refreshToken} is the refresh-token retrieved at step 2

In case of success the response is a 200 formatted as follows

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "access_token":"{accessToken}",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"{refreshToken}"
}

where :

  • {accessToken} is the access token which identifies the PSU and the TPP’s application
  • {refreshToken} is the token which will allow you to retrieve a new access token (see below)

 

Revoke the access token

You will be able to test the revocation of the access token by sending the following request according to the OAuth 2.0 refresh flow (RFC 6749).

curl -X POST '{https://api-sandbox.xxx}/oauth-authorizationcode-psd2/revoke' -d 'token={accessToken}'

where :

  • {https://api-sandbox.xxx} is the sandbox host of the bank you want to test (see above)
  • {accessToken} is the access token retrieved earlier

Invoke an API

Once you have retrieved a valid access token which identifies a PSU for your application, you will be able to invoke one of the following endpoints :

  • GET /accounts
  • GET /accounts/{accountResourceId}/balances
  • GET /accounts/{accountResourceId}/transactions
  • GET /end-user-identity
  • GET /trusted-beneficiaries

This can be done by adding the access token in the Authorization header of each request (Bearer scheme). For instance :

curl -X GET '{https://api-sandbox.xxx}/psd2/v1/accounts' -H "accept: application/hal+json; charset=utf-8" -H "Signature: xxx" -H "X-Request-ID: xxx" -H "Authorization: Bearer {accessToken}"

where :

  • {https://api-sandbox.xxx} is the sandbox host of the bank you want to test (see above)
  • {accessToken} is the access token retrieved at step 2 or after a refresh
  • Signature is mandatory but are not checked so far and there is no Signature in response : just enter a dummy value.
  • X-Request-ID is also mandatory as specified by OpenAPI description

The access token can directly be used from the API documentation pages

AISP Use cases

Here are listed the access codes of some personae you can use:

  • Francis BERGOT is a customer with one personal account 
    • Access code : 123456700
  • John ROLLAND is a customer with two personals accounts (one for which the customer is the holder and the other one for which he is an attorney)
    • Access code : 123456701
    • Note that this case does not exist for the bank Max
  • SOCI BLANC is a customer with one professional account
    • Access code : 123456710
    • Note that this case does not exist for the banks Max​ and Fortuneo
  • MENAY ANNE SOPHIE is a customer with multiple spaces accesses including seven accounts (personnals and professionals)
    • Access code : 123456711
    • Note that this case does not exist for the banks Max​ and Fortuneo
  • Pierre BEAU is a customer with no account
    • Access code : 123456703
  • Samia DAUGAREIL is a customer with an account with a negative balance
    • Access code : 123456704
  • Jane DOE is a customer who didn’t provide her consent to access her data
    • Access code : 123456705
  • Régine BERGOT is a customer with one account without any transaction
    • Access code : 123456709

Note : On GET/../transactions request, the dateFrom and dateTo filters does not currently filter the transactions on the sandbox environment.

CBPII Use cases

The same personae can be used. But the coverage is each time compared to 200€ (only € are supported).

If you ask for coverage confirmation for an amount greater than 200€, it will return false.

  • Francis BERGOT

    Access code : 123456700

    IBAN of the account : FR76{bank-code}000000000000000001
  • John ROLLAND

    Access code : 123456701

    IBAN of the first account : FR76{bank-code}000000000000000002

    IBAN of the second account : FR76{bank-code}000000000000000003

    Note that this case does not exist for the bank Max
  • Pierre BEAU

    Access code : 123456703
  • Samia DAUGAREIL

    Access code : 123456704

    IBAN of the account : FR76{bank-code}000000000000000004
  • Jane DOE

    Access code : 123456705
  • Régine BERGOT

    Access code : 123456709

    IBAN of the account : FR76{bank-code}000000000000000005

where {bank-code} depends on the bank you want to test :

  • Crédit Mutuel de Bretagne : 15589
  • Crédit Mutuel du Sud-Ouest : 15589
  • Fortuneo : 14518
  • Max : 11658
  • Arkéa Banque Privée : 15900
  • Arkéa Banque Entreprises et Institutionnels : 15589
  • Arkéa Banking Services : 15589
  • BPE : 15589
  • Allianz Banque : 15589

PISP Sandbox

If you are a PISP, you will be able to test the following endpoints :

  • POST /payment-requests
  • GET /payment-requests/{paymentRequestResourceId}
  • PUT /payment-requests/{paymentRequestResourceId}
  • POST /payment-requests/{paymentRequestResourceId}/confirmation

To be able to invoke those endpoints, you will need to retrieve an access token. The list of use cases you can deal with is provided at the end of this page.

How to retrieve the access token ?

We follow the OAuth 2.0 Authorization Code Grant as described in RFC 6749. Here is a quick description for the sandbox mode.

Step1 - Get the access token

This is done by sending the following request according to the OAuth 2.0 Authorization Code Grant.

curl -X POST '{https://api-sandbox.xxx}/oauth-clientcredentials-psd2/token' -d 'client_id={clientId}&grant_type=client_credentials'

where :

  • {https://api-sandbox.xxx} is the sandbox host of the bank you want to test (see above)
  • {clientId} is the API key of your application

In case of success the response is a 200 formatted as follows

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "access_token":"{accessToken}",
    "token_type":"Bearer",
    "expires_in":3600,
}

where :

  • {accessToken} is the access token which identifies the TPP’s application

Revoke the access token

You will be able to test the revocation of the access token by sending the following request according to the OAuth 2.0 refresh flow (RFC 6749).

curl -X POST {https://api-sandbox.xxx}/oauth-authorizationcode-psd2/revoke -d 'token={accessToken}'

where :

  • {https://api-sandbox.xxx} is the sandbox host of the bank you want to test (see above)
  • {accessToken} is the access token retrieved at step 2 or after a refresh

Invoke an API

Once you have retrieved a valid access token which identifies your application, you will be able to invoke one of the following endpoints :

  • POST /payment-requests
  • GET /payment-requests/{paymentRequestResourceId}s
  • PUT /payment-requests/{paymentRequestResourceId}
  • POST /payment-requests/{paymentRequestResourceId}/confirmation

This can be done by adding the access token in the Authorization header of each request (Bearer scheme). For instance :

curl -X POST '{https://api-sandbox.xxx}/psd2/v1/payment-requests' -H "accept: application/hal+json; charset=utf-8" -H "Authorization: Bearer {accessToken}" -H "Signature: xxx" -H "X-Request-ID: xxx" -H "Content-Type: application/json" -d "{...}

where :

  • {https://api-sandbox.xxx} is the sandbox host of the bank you want to test (see above)
  • {accessToken} is the access token retrieved earlier
  • Signature is mandatory but are not checked so far and there is no Signature in response : just enter a dummy value.
  • X-Request-ID is also mandatory as specified by OpenAPI description

In case of success the POST /payment-requests endpoint returns consentApproval href link. In sandbox mode, this link cannot be followed.

The access token can directly be used from the API documentation pages.

PISP Use cases

Depending on the use cases described hereafter, the PISP Sandbox will run a dedicated scenario.

  • First, you have to create a payment request thanks to the POST /payment-requests endpoint

    The returned consentApproval URL is not invocable so far.
  • Then, depending on the use case, you will have to assume the Arkéa payment service user acknowledged the payment request or not

The payment service user (PSU) access code which identifies the use case can be specified in the payment request (identification field of the debtor description). For instance :

"debtor": {
    "name": "TOTO TATA", 
    "postalAddress": { 
        "country": "FR", 
        "addressLine": [ "1 rue Louis Lichou", "29480 LE RELECQ-KERHUON" ] 
    }, 
    "privateId": { 
        "identification": "123456751", 
        "schemeName": "BANK", 
        "issuer": "CMBRFR2BARK" 
    } 
}

Immediately after receiving the response for your payment requests (POST /payment-requests), informations are immediately available (GET /payment-requests/{paymentRequestResourceId}) in a "pending customer validation" state (ACTC for both payment request and transactions).

As in production, these states will evolve after a 30-minutes period to become "rejected" (RJCT) due to the lack of customer validation within this time.

To be able to test cases like customer refusal/acceptance, as well as common functional cases (like "closed account", "unsuccessful balance", etc ...), just specify the access codes of the PSU in the body of your POST /payment-requests (debtor.privateId.information: 123456789).

Here are listed the access codes of some personae you can use for that :

  • Access code : 123456751 is a customer for whom payment requests are systematically rejected by the customer
  • Access code : 123456752 is a customer for whom payment requests are systematically validated by the client - Treatment completed successfully
  • Access code : 123456753 is a customer for whom payment requests are systematically validated by the client - pending processing (PDNG)
  • Access code : 123456755 is a customer for whom payment requests are systematically rejected for the reason : "invalid account number" 
  • Access code : 123456756 is a customer for whom payment requests are systematically rejected for the reason : "closed account number"  
  • Access code : 123456757 is a customer for whom payment requests are systematically rejected for the reason : "type of transaction is prohibited for the account" 
  • Access code : 123456758 is a customer for whom payment requests are systematically rejected for unspecified reason (blocked account ...)
  • Access code : 123456759 is a customer for whom payment requests are systematically rejected for the reason : "request is considered fraudulent"
  • Access code : 123456760 is a customer for whom payment requests are systematically rejected for the reason : "exceeded ceiling"
  • Access code : 123456761 is a customer for whom payment requests are systematically rejected for the reason : "insufficient account balance"

eIDAS certificate specificities

PSD2 RTS indicates that for the purpose of identification, the TPP must use eIDAS certificates, with PSD2 supplementary information: registration number, PSD2 scopes. There are 2 kinds of certificates management:

  • QWAC, used for authentication
  • and QSealC, used for requests signatures (and identification in fallback mode  - see contingency measures)

 

In the sandbox, the certificate support is not fully done. Furthermore, for some parts, you can choose to implement it or not to ease the first steps of development. Moreover, if you want to use a test's certificate, you can use the header [arkea-sandbox: certificate=nocheck] ; so, we won't check your certificate at all.

But keep in mind that in the production environment, the eIDAS certificate usage for authentication and signature will be mandatory and eIDAS certificates control will be fully done.

 

First, up to now, on Arkea PSD2 API, the server certificates are not eIDAS certificates. This will be changed in the next weeks.

For the "try it" mode, in order to be compatible with browsers, "regular" server certificates will be still used.

 

mTLS is not mandatory in the sandbox.

  • You can connect to the sandbox in TLS, without using your own QWAC certificate.
  • Or you can choose the mTLS connection. If you choose this option, the certificate control (including eIDAS conformity) will be done. You also have to set the certificate chain in your application in this portal.

 

Sign request is not mandatory in the sandbox.

  • As the signature header is mandatory in the swagger, you just have to fill this header with a dummy value (as "xxxxx").
  • Or you can choose to really sign the request. In this case, the signature must follow the draft http-signature and the description done in STET documentation. This means, for instance, that you put on the web the certificate file and indicate in the signature the URL of this file. At this stage, Arkea server doesn't check that the certificate used to sign is really an eIDAS certificate. This will be done in the next weeks.