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
  • 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
  • Axa Banque : https://api-sandbox.arkea.com 
    Please refer to the "production" page for more information on how to target a specific version.

 

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 (redirectUri must be equal (or start with) to the path declared in the developper portal).
  • {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
  • SOCI BLANC is a customer with one professional account and one international beneficiary
    • Access code : 123456710
    • Note that this case does not exist for the bank 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 bank 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
  • 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
  • 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/{id}/o-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.

The o-confirmation endpoint is protected by a dedicated token that you can obtain once the PSU has completed the validation process.

In sandbox mode, the PSU validation is replaced by a mock endpoint so the TPP can test all the process.

How to retrieve the initial access token ?

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

Get the access token

This is done by sending the following request according to the OAuth 2.0 Client Credentials 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

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

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}
  • PUT /payment-requests/{paymentRequestResourceId}

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; version=1.4.2; 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 is not controled in sandbox mode and there is no Signature in response : just enter a dummy value.
  • X-Request-ID is also mandatory as specified by OpenAPI description
  • The Accept header contains the target version.

In case of success the POST /payment-requests endpoint returns consentApproval href link. In sandbox mode, this link cannot be followed. It contains a query parameter PRid, which is the ID of the payement request you just created.

Mock the PSU validation process

Since the 1.4.2 PSD2 version, the PSU validation is not the end of the process : in order to trigger the payement, the TPP must call the o-confirmation endpoint afterwards.

This can only be done with a dedicated oauth token, that the TPP will retrieve after the PSU validation process.

In sandbox mode, the PSU validation process is replaced with a single endpoint : 

CURL -X GET https://api-public.arkea.com/psd2-psu-sandbox/approval-pisp?account={accountID}&client_id={clientID}&prid={PRID}&psu={PSUID}

where :

  • {accountID} is the identifier of the debtor account (internal Arkea identifier)
  • {clientID} is the TPP client ID
  • {PRID} is the identifier of the payment request, which was present in the redirect url after the POST payment-request
  • {PSUID} is the identifier of the PSU (internal Arkea access code)

The allowed values of the fields "account" and "psu" can be found in the "PISP use cases" section.

The result will be a 302 with a location header : {tppRedirectUrl}?code={code}

  • {tppRedirectUrl} is the redirect url declared by the TPP in the devportal (redirectUri must be equal (or start with) to the path declared in the developper portal.).
  • {code} is a single-use code which will be used to retrieve the final oauth token.

In cas of failure, the location header will be :  {tppRedirectUrl}?error=access_denied and no code will be provided.

 

Get the TPP access token Validation from the authorization-code

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-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":"{TppValAccessToken}",
    "token_type":"Bearer",
    "expires_in":3600
}

where :

  • {TppValAccessToken} is the access token which identifies the PSU for the current payment-request initiated by the TPP’s application identified by its client_id

O-confirmation

Once you have retrieved a valid access token for the o-confirmation, you can use it to finalize the payment :

  • POST /payment-requests/{paymentRequestResourceId}/o-confirmation

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

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

The final status of the payment-request can be checked by the TPP using the GET /payment-requests/{paymentRequestResourceId} endpoint.

 

 

PISP Use cases

The PISP Sandbox can only manage a few personae. They are listed below.

  • First, you have to create a payment request thanks to the POST /payment-requests endpoint
    The returned consentApproval URL is not invocable so far.

The payment service user (PSU) access code which identifies the use case can optionally 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": "123456770", 
        "schemeName": "BANK", 
        "issuer": "CMBRFR2BARK" 
    } 
}

You can the use the PSU mock endpoint and o-confirmation to finalize the payment.

As in production, the states of the payment-request will evolve after a 30-minutes period to become "rejected" (RJCT) if the final state of the process has not be reached.

Here are the access code and account you can use :

  • Access code : 123456770, account : TE123456.  
  • debtoraccount :  
  • "debtorAccount": {"iban": "FR7615589999999999999999999"   
  • It has a balance of 1000€ : a payment with an amount above this value will fail.
  • Any other access code or account will a result in a failure.

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.