Production

Introduction

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

 

 

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 V1.4.1 & V1.4.2

The version 1.4.1 will be replace by the 1.4.2 version soon (see the migration phase is described here). Even if the process of retrieving the access token remains unchanged, you will be able to manage the version you want to deal with.

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. 

Step1 - Access token

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

 

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?response_type=code&client_id={clientId}&redirect_uri={redirectUrl}&scope={scope}&state={state}

where :

  • {clientId} is the API key of your application
  • {redirectUrl} is the callback URL you have provided in the application description
  • {scope} can take the following values 
    • "aisp" or "aisp extended_transaction_history" for an AISP
    • "cbpii" for a CBPII
  • {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&state={state}

 

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 the access token

You will be able to revoke the access token by sending the following request according to the OAuth 2.0 revoke 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

 

Step2 - 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 
  • POST /funds-confirmations

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 "Accept: version=1.4.2" -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

To be able to use the version 1.4.2, you simply have to put an Accept header in your requests.

Accept: version=1.4.2

With multiple values in Accept header 

Accept: application/json; version=1.4.2

You do not have to use a different URL or a different App (the same client_id can be used).

PISP V1.4.1

The version 1.4.1 is deprecated (see the migration phase is described here). If you start to use our APIs we encourage you to follow the PISP V1.4.2 section bellow.

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

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

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 Client Credentials Grant as described in RFC 6749. Here is a quick description. 

 

Step1 - Access token

Get the access token by sending the following request according to the OAuth 2.0 Client Credentials 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 the access token by sending the following request according to the OAuth 2.0 revoke 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

 

Step2 - 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-host.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.

 

PISP V1.4.2

The version 1.4.2 introduces the Enforced Redirect flow. Hence you will have to use follow two OAuth 2.0 flows to be able to complete a payment.

{tppAccessToken} identifies the TPP and is retrieved by following the OAuth 2.0 Client Credentials Grant as described in RFC 6749. It can be used to invoke the following endpoints :

  • POST /payment-requests to initiate a payment-request 
  • GET /payment-requests/{paymentRequestResourceId} to retrieve a payment-request
  • PUT /payment-requests/{paymentRequestResourceId} to cancel a payment-request

{psuAccessToken} identifies the Payment Service User (PSU) for this TPP and a dedicated payment-request. It is retrieved by following the OAuth 2.0 Authorization Code Grant as described in RFC 6749. It can be used to confirm the payment-request on behalf of the PSU by using the following endpoint :

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

 

Manage the TPP access token

Get the access token by sending the following request according to the OAuth 2.0 Client Credentials 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":"{tppAccessToken}",
    "token_type":"Bearer",
    "expires_in":3600,
}

where :

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

 

Revoke access token

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

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

where :

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

 

Use the {tppAccessToken} to initiate, retrieve or cancel a payment-request

Once you have retrieved a valid TPP 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-host.xxx}/psd2/v1/payment-requests -H "accept: application/hal+json; charset=utf-8" -H "Authorization: Bearer {accessToken}" -H "Accept: version=1.4.2" -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 : see section bellow

 

Retrieve PSU access token to confirm a payment-request

A payment-request is initiated by invoking the endpoint POST /payment-requests (see the previous section). In case of success, the 201 Created response is formated as follows 

{
  "appliedAuthenticationApproach":"REDIRECT",
  "_links":{
    "consentApproval":{
      "href":"{approvalUrl}?PRid={PRid}&response_type=code&scope=pisp"
    }
  }
}

where :

  • {approvalUrl} is the path to the validation application (Redirect Approach)
  • {PRid} is the identifier of the created payment-request

Note that the consentApproval URL is already completed with the response-type and scope parameters. We will have to complete this URL with your client_id, redirect_uri and state as described bellow

 

Retrieve the authorization-code by redirecting the Arkea Payment Service User (PSU) to the consentApproval URL

curl -X GET {approvalUrl}?PRid={PRid}&response_type=code&scope=pisp&client_id={clientId}&redirect_uri={redirectUrl}&state={state}

where :

  • {clientId} is the API key of your application
    This parameter is mandatory
  • {redirectUrl} is the callback URL you have provided in the application description
    This parameter is optional
    If it is not specified, the callback URL associated to the application identified by the {clientId} will be used
    If it is specified, it must match (basepath at least) the callback URL associated to the application identified by the {clientId}
  • {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 optional. 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

In case of success (when the PSU accept the initiated payment), the PSU will be automatically redirected to the {redirectUrl} 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 or the callback URL associated to the application
  • {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&state={state}

 

Get the PSU access 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":"{psuAccessToken}",
    "token_type":"Bearer",
    "expires_in":3600
}

where :

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

 

Confirm the payment-request

Once you have retrieved a valid PSU access token you will be able to confirm the payment-request by invoking the endpoint POST /payment-requests/{paymentRequestResourceId}/o-confirmation

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

curl -X POST {https://api-host.xxx}/psd2/v1/payment-requests/{paymentRequestResourceId}/o-confirmation -H "Authorization: Bearer {psuAccessToken}" -H "Accept: version=1.4.2" -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
  • {psuAccessToken} is the PSU access token retrieved at earlier