Production

Introduction

Access to the production environment is open to TPPs (PSD2 licensed players) for personal and business bank accounts using our APIs.

For Arkea Banque Entreprises et Institutionnels, APIs are not yet available : it is possible to use our fallback mechanism described here.

The fallback mechanism is open to TPPs for personal and business bank accounts. To use the fallback mechanism, a creation of a developer application for each bank is required.

 

 

You have several steps to follow :

  1. Create a developer account or log-in
  2. Create an application to obtain an API key
  • The application has to be created with your TPP identifier and the associated QwaC, and a QSealC (to be able to sign your requests) This information will be checked in the official repositories.
  • 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
  • You will have to create an application for each bank hosted by Arkéa
  1. Retrieve access token (see AISP/CBPII or PISP descriptions below)
  2. Use the API by requesting the following URLs (in a mutual TLS connection, using your QwaC) depending on the bank you want to interact with:
  • Crédit Mutuel de Bretagne : https://api-openbanking.cmb.fr
  • Crédit Mutuel du Sud-Ouest : https://api-openbanking.cmso.com
  • Fortuneo : https://api-openbanking.fortuneo.com
  • Max : https://api-openbanking.max.fr
  • Arkéa Banque Privée : https://api-openbanking.arkeabanqueprivee.fr
  • Arkéa Banque Entreprises et Institutionnels : https://api-openbanking.arkea-banque-ei.com
  • Arkéa Banking Services : https://api-openbanking.arkea-banking-services.com
  • BPE : https://api-openbanking.bpe.fr
  • Allianz Banque : https://api-openbanking.allianzbanque.fr

AISP/CBPII

if you are an AISP, you will be able to invoke 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 invoke 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. 

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. 

 

Step1 - Retrieve the authorization-code by redirecting the Arkea Payment Service User (PSU) to the relevant bank’s authorization infrastructure, through the following URL pattern and parameters. 

curl -X GET https://{bank-fqdn}/authorize -d 'response_type=code&client_id={clientId}&redirect_uri={redirectUrl}&scope=aisp&state={state}'

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. If you specify this parameter, please note that the value cannot contain the character comma (',') because it would cause the split of the Location header in 302 response
  • {bank-fqdn} is the FQDN of the bank you want to interact with:
    • Crédit Mutuel de Bretagne : openbanking.cmb.fr
    • Crédit Mutuel du Sud-Ouest : openbanking.cmso.com
    • Fortuneo : sca-openbanking.fortuneo.com
    • Max : openbanking.max.fr
    • Arkéa Banque Privée : openbanking.arkeabanqueprivee.fr
    • Arkéa Banque Entreprises et Institutionnels : openbanking.arkea-banque-ei.com
    • Arkéa Banking Services : openbanking.arkea-banking-services.com
    • BPE : openbanking.bpe.fr
    • Allianz Banque : openbanking.allianzbanque.fr

In case of success the PSU will be automatically redirected to the URL you provided thanks to 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 PSU will be automatically redirected to the URL you provided thanks to 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 -X POST {https://api-host.xxx}/oauth-authorizationcode-psd2/token -d 'client_id={clientId}&grant_type=authorization_code&redirect_uri={redirectUrl}&code={code}'

where :

  • {https://api-host.xxx} is the API host of the bank you want to interact with :
    • Crédit Mutuel de Bretagne : https://api-openbanking.cmb.fr
    • Crédit Mutuel du Sud-Ouest : https://api-openbanking.cmso.com
    • Fortuneo : https://api-openbanking.fortuneo.com
    • Max : https://api-openbanking.max.fr
    • Arkéa Banque Privée : https://api-openbanking.arkeabanqueprivee.fr
    • Arkéa Banque Entreprises et Institutionnels : https://api-openbanking.arkea-banque-ei.com
    • Arkéa Banking Services : https://api-openbanking.arkea-banking-services.com
    • BPE : https://api-openbanking.bpe.fr
    • Allianz Banque : https://api-openbanking.allianzbanque.fr
  • {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

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

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

where :

  • {https://api-host.xxx} is the API host of the bank you want to interact with
  • {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 access token

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

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

where :

  • {https://api-host.xxx} is the API host of the bank you want to interact with
  • {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 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-host.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-host.xxx} is the API host of the bank you want to interact with
  • {accessToken} is the access token retrieved at step 2 or after a refresh

PISP

 you are a PISP, you will be able to invoke 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.

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. 

 

Step2 - 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-host.xxx}/oauth-clientcredentials-psd2/token -d 'client_id={clientId}&grant_type=client_credentials'

where :

  • {https://api-host.xxx} is the API host of the bank you want to interact with :
    • Crédit Mutuel de Bretagne : https://api-openbanking.cmb.fr
    • Crédit Mutuel du Sud-Ouest : https://api-openbanking.cmso.com
    • Fortuneo : https://api-openbanking.fortuneo.com
    • Max : https://api-openbanking.max.fr
    • Arkéa Banque Privée : https://api-openbanking.arkeabanqueprivee.fr
    • Arkéa Banque Entreprises et Institutionnels : https://api-openbanking.arkea-banque-ei.com
    • Arkéa Banking Services : https://api-openbanking.arkea-banking-services.com
    • BPE : https://api-openbanking.bpe.fr
    • Allianz Banque : https://api-openbanking.allianzbanque.fr
  • {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 access token

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

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

where :

  • {https://api-host.xxx} is the API host of the bank you want to interact with
  • {accessToken} is the access token retrieved earlier

 

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}
  • 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-host.xxx} is the API host of the bank you want to interact with
  • {accessToken} is the access token retrieved earlier

In case of success the POST /payment-requests endpoint returns consentApproval href link you will have to follow to ask for the PSU to validate the payment request.