Get Started

1. Welcome

Welcome to the Rothschild Martin Maurel Developer Portal. This portal will allow you to access the Rothschild Martin Maurel API documentation and to test your app against the Sandbox environment before using it with real customer data.

The developer portal is available at https://developer.espace-prive.com.

We base our APIs on current industry standards and best practices Rothschild Martin Maurel API is based on the STET specification [https://www.stet.eu/en/psd2/].

Check out the steps below to find out how you can register and start consuming our APIs.

1.1 Security is our priority

Our APIs comply with the REST style. They use HTTP over TLS for transport and JSON as representation. They communicate errors using the HTTP status codes you would expect, and include developer-friendly error messages. Furthermore, our APIs implement the latest security standards, and include multiple lines of defense to ensure that user data is safe and protected, a.o eIDAS QWAC and QSEAL certificates.

The eIDAS QWAC certificate is used to establish a mutual authentication between you and Rothschild Martin Maurel. It creates a channel for communication with the subject of the certificate using the transport layer security (TLS) protocol, which guarantees confidentiality, integrity and authenticity of all data transferred through the channel. This means that the system connecting to the website presenting the certificate can be sure:

who owns the end point of the communication channel (the owner of the certificate)
that the data was not changed between the end points
that nobody else could have read the data along the way.

However, the data communicated by the QWAC are only protected while they are travelling through the TLS channel. Therefore, the system connecting to the website can be sure who they are communicating with but cannot prove this to third parties, which means that QWACs alone do not give legally assumed evidence of a transaction.

To elaborate the evidence, we compliment mutual authentication with message signatures using the eIDAS QSEAL certificate of the TPP.

QSEAL certificate makes it possible for the owner of the certificate to create electronic seals on any data to ensure the integrity and correctness of the origin (authenticity) of the signed data. This means that the system receiving digitally signed data can be sure who signed the data, that the data have not been changed since being signed and that they can also present these signed data to third parties as evidence of who signed the data and that they were not changed after being signed.

For these reasons, Rothschild Martin Maurel use both QWAC and QSEAL certificates to ensure safe transactions to our customers and other stakeholders acting on behalf of them.

2. Company registration

Before you get ready using the Rothschild Martin Maurel APIs, you must register yourself and your company to the Rothschild Martin Maurel developer portal [https://developer.espace-prive.com].

2.1. Prerequisites

Before starting, you must have proceeded the following:

Be registered as a TPP by your National competent authority (ACPR in France, NBB in Belgium, …) that will grant you a registration id.
Get PSD2 QWAC and QSEAL eIDAS certificates from a certified QTSP [https://webgate.ec.europa.eu/tl-browser/#/].
- The QWAC certificate is used for setting up a mutual TLS authentication
- The QSEAL certificate is used for signing the request messages

2.2. Sign up

Go to the Rothschild Martin Maurel developer portal: https://developer.espace-prive.com and sign up (link at the top right corner).

You must provide the following information:

Your company name
Your first name
Your last name
Your email address
A password that must match complexity requirements as follows
- Length of at least 8 characters
- Must contain at least one - UPPERCASE, lowercase, digit and special character
Repeat your password

Once your account is approved, you will receive an e-mail with activation link. You must use the activation link before logging in for the first time.

2.3. Create, join or leave a team

Before getting access to our Developer portal you need to join or create a team based on your PSP Registration ID.

2.3.1 Create a team

If you are the first developer of your company to register on the developer portal, you have to create a team based on the QWAC and QSEAL certificates. The other fields will be automatically filled thanks to the information contained in the QWAC certificate.

When the team is created, you will become its administrator and you will have access to the team management panel. It is divided in two parts:

Team members: In this part, there is a table listing all registered users of your team with their roles. At the beginning, you will be alone in the team but each time a new developer joins your team the table will grow.
In the top of the table, you have the administrators and then the developers sorted by the "User information". As administrator, you will be able to change the role of a user, remove a user from the team or leave your team.
Pending requests: When a new developer is trying to join your team, you will receive an email and the information about him will be listed in the second part of the team management panel. You will be able to validate or remove a pending request.

2.3.2 Join a team

You have to give the PSP Registration ID of the team you want to join and validate your demand. An email will be automatically sent to the team's administrator. Once he accepted you, you will be considered as developer and you will have access to the created Apps and you will only see the team members part in the team management panel.

2.3.3 Leave a team

There are different cases:

There are several developers and you are the administrator: Before leaving the team, you have to promote a developer as administrator.
There are several developers and administrators and you are the administrator: You can leave the team without any problem because there is at least one other administrator.
There are only administrators in the team and you are one of them: Same case as above.
You are administrator without any colleagues: If there are still some active Apps, you can't directly leave the team. You have to delete them first before leaving.
You are a developer: You can leave the team without any restrictions because there is still at least one administrator.

2.4. Explore the APIs

There are currently three groups of APIs for the detailed information of each API, see the API documentation guide.

XS2A: Access to Accounts, including balances, beneficiaries and transactions. Credit card transactions are also available.
Payment Initiation: it includes single SEPA credit transfers, bulk SEPA credit transfers and standing orders (recurrent payments).
Funds coverage: it allows to check the availability of funds on a given account or card.

2.5. Create your app

Now you are ready to go:

Create your app in the portal: this requires the name of your app.
Then upload your PSD2 client public eIDAS certificates from which we can retrieve your registration id, your role(s), your country and your competent registration authority.

Good to know

You can upload different certificates for real data access than for the sandbox. These certificates can be uploaded later, once your application has been tested against the sandbox and you are ready using it with real customer data.

2.5.1. OAuth 2.0 Dynamic Client Registration Protocol

We are not compliant with OAuth 2.0 Dynamic Client Registration Protocol.

Select the API your app will subscribe to. You can only subscribe an API that is compatible with your role(s). If you want to subscribe to more than one API, you must create multiple apps in the portal
Register your OAuth2 redirect URLs (mandatory) in the developer portal.
- The root redirect URL (required if relative URLs are given)
- One or more Redirect URLs
- The Base redirect URL: optional field of your app when we redirect the customer in case of error
Ensure that your application is subscribed to the API with the roles you want to request from the customer.
Obtain the application credentials. When adding an application, the OAUTH2 ClientId will be automatically generated. You will need this clientId to call the API. If you have the roles that allow you using the XS2A services and the payment initiation services, you must create two different apps and will get two different ClientId.

2.6. Partnership models

Some national competent authorities, and especially the ACPR in France, support different models of partnership developed by the TPPs to extend their activities. These different models are supported by Rothschild Martin Maurel.

2.6.1 "White label" model

The partner offers a service combining recovery and exploitation of the collected data and uses the services of an AISP as an outsourced essential service provider to collect account information.

In this context, the customer subscribes to a single contract with the partner who provides from the contractual point of view the account information payment service: the partner must then be authorized as an AISP by a European competent authority.

As the partner is recognized as an AISP with its own PSD2 authorization code, he must subscribe to the developer portal as any other TPP. There is as such no difference with the standard model.

2.6.2 "Co-branding" model

The partner offers a service combining recovery and exploitation of the collected data and uses the services of an AISP as an outsourced essential service provider to collect account information.

The partner offers a service combining the retrieval and exploitation of the collected data but offers the information service on accounts "on behalf of" an AISP. In this context, the customer subscribes with the partner either a tripartite contract with the partner and the AISP, or a bilateral contract with the partner in which it is mentioned that the partner is mandated by the AISP to engage on its behalf. The partner must then be mandated as an AISP agent. Payment services are provided under the responsibility of the TPP which has, moreover, a power of control on the partner.

In this model, the partner must not be registered by the bank on the developer portal. Only the TPP he is acting on behalf of must be registered once. The TPP can however define different apps (one for each partner). Consents are defined for each app (and therefore for each partner).

2.6.3 "Redirection" or "Third-party user" model

The partner offers only the data exploitation service and offers the customer to directly subscribe the data recovery service from an AISP.

The PSU then subscribes to two contracts: a contract with the AISP for the recovery of the account data in which it explicitly authorizes their transmission to the partner and a contract with the partner for the exploitation of the data.

In this model, only the AISP must register to the developer portal and an app must be created for each partner he is acting for. Consents are defined for each app and then for each partner.

3. Access to APIs

3.1. Get access for AISP and CBPII services

Some APIs require preliminary consent from the customer. In this case, you will use the OAuth2 Authorization code grant flow, which will provide your application with specific access- and refresh tokens for getting the customer data approved by the customer.

To start the flow, you just need to obtain an application access token with the "granting" scope to start the OAuth2 Authorization Grant code flow.

For AISP and CBPII, getting an access token follows the OAUTH2 Authorization Grant flow (cf https://tools.ietf.org/html/rfc6749#section-4.1). It requires two steps:

The client (your app) initiates the flow and requests an authorization code to Rothschild Martin Maurel. If the end-customer gives his/her consent, a short lifespan authorization code is returned to the client.
With the authorization code, the client can ask the access and refresh tokens to Rothschild Martin Maurel. The QWAC certificate is required to carry out this step. The access token has a short lifetime while the refresh token has a lifetime correlated with the consent lifetime.

The complete flow between the customer, your app and Rothschild Martin Maurel should look like this:

The customer instructs you to make a connection between your app and Rothschild Martin Maurel
Your app redirects the customer to Rothschild Martin Maurel
The customer will authenticate himself in the secured and trusted Rothschild Martin Maurel environment
The consent request is presented to the customer
The customer grants you access in the secured and trusted Rothschild Martin Maurel environment by signing the consent request
The customer is automatically redirected back to your app and simultaneously you receive an authorization code

You can retrieve the data for which it is granted access by the customer:

Rothschild Martin Maurel will provide your app with access and refresh tokens based on the authorization code. You can start retrieving the relevant account information using the provided access token.
Firstly, the access token can be used to request the IBAN, account-id (UUID), currency of the account and the name of the account holder of the granted payment account(s). Secondly, the combination of the access token and account-id makes it possible for your app to request the balance and transaction information of the account(s) and/or credit cards.

The consent is granted for a limited period, usually three months. When the consent is expired, the access and refresh tokens need to be renewed. Your app shall invite the customer to perform step 2-6 to get a new access token for the next 90 days.

3.1.1. AISP/CBPII Authorization code Request

You must redirect the customer to the correct endpoint to get an authorization code before accessing AISP/CBPII services.

Rothschild Martin Maurel’s OAuth 2.0 endpoint is:

Sandbox: https://api-sandbox.espace-prive.com/v2/authorize
Real data: https://api.espace-prive.com/v2/authorize

Connections are HTTPS-only, HTTP connections are refused. The current version of APIs can be retrieved in the API documentation.

You request an authorization code by doing a GET including the following parameters:

response_type: must be “code”
scope: The scopes for which you want the authorization must be specified. This could be a subset of the scopes you were registered for.
- for AISP:
  - “aisp” for standard AISP access (history of transactions restricted to 90 days)
  - “extended_transaction_history” for extended access to the history of transactions
- For CBPII: “cbpii”
client_id: UUID given through the developer portal (https://developer.espace-prive.com) when the app has been created.
state: internal state given by your app to uniquely identify the request
redirect_uri: call-back URL of the client app. This is the URL where the user will return to once the authorization process is ended. This redirectUrl should be one of the URLs you registered in the registration process.

Example (Sandbox):

https://api-sandbox.espace-prive.com/v2/authorize?response_type=code&scope=aisp&client_id=3466687a-7e3f-4c8f-b4a3-bf15fb11aaa4&state=12345&redirect_uri=https://my-callback-url

The authorization code request implies a consent given by the customer of the bank.

The following screen will be displayed to the customer:

The customer can choose his authentication flow but he must at least enter his identifier as used to access the internet banking.

Once authenticated, the customer is requested to sign the consent granted to the Third party Provider:

The customer must follow instructions regarding the authentication flow previously chosen to sign the consent request.

At the end of the process, the customer is redirected to your redirect_uri communicated in the authorization code request with a set of parameters.

Example (Sandbox): successful response to activation code request

http://my-callback-url/?state=12345&session_state=656d87dd-83ae-4fbc-8e66-84fab3e35135&code=1a87f856-a11b-4977-b220-b7ab6f833900.656d87dd-83ae-4fbc-8e66-84fab3e35135.22425f30-7d96-41c3-a1d1-922d0bbe44fd

state: state sent by you to uniquely identify the request. You must check that the state corresponds to the state that you sent in your request
session_state: internal session state, not relevant to you
code: requested authorization code that will be used to request an access token (see below). The authorization code is valid for 60 seconds.

If the customer refuses to grant the consent, the parameters of the redirect_uri are:

state: state sent by you to uniquely identify the request
error: “access_denied”

Example: error response to authorization code request

http://my-callback-url/?error=access_denied&state=12345

3.1.2. Access token Request

In order to get the access token, you are now able to call, through a POST request, the Rothschild Martin Maurel’s token endpoint:

Sandbox: https://api-sandbox.espace-prive.com/v2/token
Real data: https://api.espace-prive.com/v2/token

Example: access token request (Sandbox)

POST https:// api-sandbox.espace-prive.com/v2/token
Body (URL encoded):

    session_state=656d87dd-83ae-4fbc-8e66-84fab3e35135&code=1a87f856-a11b-4977-b220-b7ab6f833900.656d87dd-83ae-4fbc-8e66-84fab3e35135.22425f30-7d96-41c3-a1d1-922d0bbe44fd

    &grant_type=authorization_code

    &redirect_uri= my-callback-url

    &client_id=3466687a-7e3f-4c8f-b4a3-bf15fb11aaa4

Make sure to URL encode the body.

Rothschild Martin Maurel responds with the requested tokens in JSON format:

access_token: access token provided by Rothschild Martin Maurel
token_type: “bearer”
expires_in: access token lifetime, in seconds
refresh_token: refresh token that can be used for a future token renewal request
refresh_expires_in: refresh token lifetime, in seconds
session_state: internal session state, not relevant to you
not-before-policy: Open-ID connect information Not relevant to you.
scope: initial scope provided in the authorization code request

Example of response:

{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJkeVdGdlIxQV9VZFFnUGMxb0xiVkdzQ0s3d3pxN0oxSGhRekdQUlY0ZnkwIn0.eyJqdGkiOiJmNjZhZTgyZC1kM2ZkLTRlZWMtYTgxNC1lZTRjY2E4MWNjMjQiLCJleHAiOjE1NTA1MDMwNzcsIm5iZiI6MCwiaWF0IjoxNTUwNDg4Njc3LCJpc3MiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJhdWQiOiJvcGVuYmFua2luZ19yZXN0X2FwaSIsInN1YiI6ImY6Y2YxOTA4MjMtMzM2Ny00OGY5LWEwMDctNTRlNTkzZWI0MzQ5OlQzU1RXQUMxIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiMzQ2NjY4N2EtN2UzZi00YzhmLWI0YTMtYmYxNWZiMTFhYWE0IiwiYXV0aF90aW1lIjoxNTUwNDg4NjIxLCJzZXNzaW9uX3N0YXRlIjoiNjU2ZDg3ZGQtODNhZS00ZmJjLThlNjYtODRmYWIzZTM1MTM1IiwiYWNyIjoiMSIsInNjb3BlIjoiYWlzcCIsImNsaWVudE51bWJlciI6Ijk5OTAwMDAwMDAxIiwic3Vic2NyaXB0aW9uSWQiOiIzMDAwMDAwMDAwMDUifQ.FV7YlEUFwx4m2PmjBv_XqWa8Si7Vrdt-SrqB-I1mhPU--gQWrBpxa7aeuhXrLqyzURXHTp-R2PmU8-A-83dJtsg9R9rYeUpaa_nNsVHiAJsuT3voJk8k1Je5_hRDQ3kvcOFrKj9Y2aepOPKXe53pHZaIfIvmGRZPBo8qK8LEsT0eLnLyufeB1sgGdNjc8YsFV_iRt-RCAiS29kk3o9mSBdgoznd5ZQKzNa6zFc2nehtv7VbOqdGUCeJoEBRGEHTFYy58rbnaDFs_lb0u4Boz8Q9ZaqRto_daTOXKkCJzQJkjcesxRJ9WRnzxWJqpPtmzapgasERD6egxgv9yUosWcg",
    
"expires_in": 300,
    
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyOTNiZDllMy0wMDJlLTQ4OTYtYjg0Ny0xODdlMDkzNjdmZGQifQ.eyJqdGkiOiIyMTRlYmJlYi1kZThlLTRhOTctOTc3Ni0yNjFlZjVjNTk4MzMiLCJleHAiOjE1NTgyNjQ0ODIsIm5iZiI6MCwiaWF0IjoxNTUwNDg4Njc3LCJpc3MiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJhdWQiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJzdWIiOiJmOmNmMTkwODIzLTMzNjctNDhmOS1hMDA3LTU0ZTU5M2ViNDM0OTpUM1NUV0FDMSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiIzNDY2Njg3YS03ZTNmLTRjOGYtYjRhMy1iZjE1ZmIxMWFhYTQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI2NTZkODdkZC04M2FlLTRmYmMtOGU2Ni04NGZhYjNlMzUxMzUiLCJzY29wZSI6ImFpc3AifQ.5lQei5L1DtWoSX1GekqRqEenDnjgdrDPleISN7Ouq1Y",

"token_type": "bearer",
    
"not-before-policy": 0,
    
"session_state": "656d87dd-83ae-4fbc-8e66-84fab3e35135",
    
"scope": "aisp" }

The access token must be used within each request within the “Authorization” header, prefixed by the token type “Bearer”.

An access token is usually, for security reasons, valid for 5 minutes. The token lifespan can be changed by the bank without prior notice. The refresh token is valid according to the consent duration. You must store the refresh token securely in your app to be able to request a new access token.

3.1.3 Refreshing a token

The access token has an expiration time. It can be refreshed using the refresh token which is itself of course not expired.

In the Authorization code grant flow you will get a refresh token to obtain a new application access token, so you don't need to do a new authorization request. Note that the refresh token will also expire, the expiration time depends on the subscribed Rothschild Martin Maurel API (e.g 90 days). When the refresh token is expired, you need to start the Authorization grant code flow again and ask the consent of the Rothschild Martin Maurel customer.

You can ask a new access token with your refresh token. The corresponding endpoint is:

Sandbox: https://api-sandbox.espace-prive.com/v2/token
Real data: https://api.espace-prive.com/v2/token

Example: access token refresh (Sandbox)

POST https:// api-sandbox.espace-prive.com/v2/token
Body (URL encoded):

    refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyOTNiZDllMy0wMDJlLTQ4OTYtYjg0Ny0xODdlMDkzNjdmZGQifQ.eyJqdGkiOiIyMTRlYmJlYi1kZThlLTRhOTctOTc3Ni0yNjFlZjVjNTk4MzMiLCJleHAiOjE1NTgyNjQ0ODIsIm5iZiI6MCwiaWF0IjoxNTUwNDg4Njc3LCJpc3MiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJhdWQiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJzdWIiOiJmOmNmMTkwODIzLTMzNjctNDhmOS1hMDA3LTU0ZTU5M2ViNDM0OTpUM1NUV0FDMSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiIzNDY2Njg3YS03ZTNmLTRjOGYtYjRhMy1iZjE1ZmIxMWFhYTQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI2NTZkODdkZC04M2FlLTRmYmMtOGU2Ni04NGZhYjNlMzUxMzUiLCJzY29wZSI6ImFpc3AifQ.5lQei5L1DtWoSX1GekqRqEenDnjgdrDPleISN7Ouq1Y

    grant_type=refresh_token

    client_id=3466687a-7e3f-4c8f-b4a3-bf15fb11aaa4

    scope=aisp

The response is similar to the token request response, returning a new access token and a new refresh token Indeed for security reasons, once used, the refresh token is revoked and you receive a new one.

3.2. Get access for PISP services

There is no preliminary consent required to access PISP services. To start the flow, you just need to obtain an access token with the “OAUTH2 Client Credentials” flow (cf https://tools.ietf.org/html/rfc6749#section-4.4).

Once the access token received, the PISP flow for a payment initiated by the payee (e-commerce payment) should look like this:

The customer is checking out his/her purchase basket and is selecting your app as payment means
The customer gives Rothschild Martin Maurel as bank holding his/her account
Your app sends the details of the payment transaction to Rothschild Martin Maurel via the Payment Initiation API
Rothschild Martin Maurel will provide an URL to the PISP, which can be used by the customer to sign the payment transaction
Your app redirects the customer to Rothschild Martin Maurel by means of the provided URL
The customer will authenticate himself/herself in the secured and trusted Rothschild Martin Maurel environment
The customer can simply select a debit account out of the list of his/her payment accounts
Rothschild Martin Maurel performs the regular checks as for payments initiated via Rothschild Martin Maurel customer channels, including a check on sufficient balance
The customer authorizes the payment in the secured and trusted Rothschild Martin Maurel environment
In case of positive outcome of the regular checks and a successful authorization, Rothschild Martin Maurel sends an “OK” back to the PISP and starts processing the payment transaction
The customer is automatically directed back to your app

3.2.1. PISP access token request

In order to get the access token, you can call, through a POST request, the Rothschild Martin Maurel’s token endpoint:

Sandbox: https://api-sandbox.espace-prive.com/v2/token
Real data: https://api.espace-prive.com/v2/token

Example: access token request

POST https:// api.espace-prive.com/v2/token
Body (URL encoded):

    &grant_type= client_credentials

    &scope=pisp

    &client_id= f82f2b65-256d-45a4-b9c9-46be26cd4cf1

Make sure to URL encode the body.

Rothschild Martin Maurel responds with the requested tokens in JSON format:

access_token: access token provided by Rothschild Martin Maurel
token_type: “bearer”
expires_in: access token lifetime, in seconds
refresh_token: refresh token that can be used for a future token renewal request
refresh_expires_in: refresh token lifetime, in seconds
session_state: internal session state, not relevant to you
not-before-policy: Open-ID connect information Not relevant to you.
scope: initial scope provided in the authorization code request

Example of response:

{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJkeVdGdlIxQV9VZFFnUGMxb0xiVkdzQ0s3d3pxN0oxSGhRekdQUlY0ZnkwIn0.eyJqdGkiOiI4OGUxMDQ4NC1jZDY3LTRiZDMtOWViNy00MTlkNzQ5ZWI4ZDkiLCJleHAiOjE1NTA3Njg0NjYsIm5iZiI6MCwiaWF0IjoxNTUwNzU0MDY2LCJpc3MiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJhdWQiOiJvcGVuYmFua2luZ19yZXN0X2FwaSIsInN1YiI6ImZiMGE4ZWE0LTUzNjktNGMzNC1hZWQzLWI2OWNkNjQ5MmFmOSIsInR5cCI6IkJlYXJlciIsImF6cCI6ImY4MmYyYjY1LTI1NmQtNDVhNC1iOWM5LTQ2YmUyNmNkNGNmMSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6ImQyMTg1NDk3LWE0YjAtNDRjOS04Y2U4LWEwMzRkZGIyMWFiZSIsImFjciI6IjEiLCJzY29wZSI6InBpc3AiLCJjbGllbnRJZCI6ImY4MmYyYjY1LTI1NmQtNDVhNC1iOWM5LTQ2YmUyNmNkNGNmMSIsImNsaWVudEhvc3QiOiIxOTIuMTAwLjMuNjQiLCJjbGllbnRBZGRyZXNzIjoiMTkyLjEwMC4zLjY0In0.FJ_s_LJGXF3o2P8xDP9sTl9wSR37mRLgyAIBsE7wBkn9Hx61UotqGNw-cdcIGgD9973ROq_slrn3MUQXTfP00EIHb_qOGBJHw3mXxosBFmByWOf-9PForBm4wLi4ET1AqITKzqSDCgCDLLBQRRnzI2zHdXaxRMZ3mw9uxbRKe0fJ4a5Hmz3b_IhblNUqSkgeuwH4qHfVy2SN17Y3WVkexo8GLGG7ZYkqWUe565F38COZYMzXzj58nqmUldEo6yjQLvSTBbm3bvhvLPQmQyzEXI2uT03_u7flk5Ebhr2E2I78Peszfe9gBT_yp6BHg680AEgTzIe5-wE2LhnHNGLUpA",

"expires_in": 300,

"refresh_expires_in": 7776000,

"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyOTNiZDllMy0wMDJlLTQ4OTYtYjg0Ny0xODdlMDkzNjdmZGQifQ.eyJqdGkiOiI2MDUxZDI5ZC1lMGQzLTQ3MzktYmQ0ZC01OTk3MDUzOGQ5YTkiLCJleHAiOjE1NTg1MzAwNjYsIm5iZiI6MCwiaWF0IjoxNTUwNzU0MDY2LCJpc3MiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJhdWQiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstcm1tOjg0NDMvYXV0aC9yZWFsbXMvZmhvbWUiLCJzdWIiOiJmYjBhOGVhNC01MzY5LTRjMzQtYWVkMy1iNjljZDY0OTJhZjkiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiZjgyZjJiNjUtMjU2ZC00NWE0LWI5YzktNDZiZTI2Y2Q0Y2YxIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiZDIxODU0OTctYTRiMC00NGM5LThjZTgtYTAzNGRkYjIxYWJlIiwic2NvcGUiOiJwaXNwIn0.Y6ePMP312mhuV8nrqop4BYKHOGDrHCYQHpk1OFv9Gig",

"token_type": "bearer",

"not-before-policy": 0,

"session_state": "d2185497-a4b0-44c9-8ce8-a034ddb21abe",

"scope": "pisp" }

The access token must be used within each request within the “Authorization” header, prefixed by the token type “Bearer”.

The refresh token is not used in this flow. When the access token is expired, just follow the same process to get a new access token.

3.2.1.1. PISP Authorization code Request

You must get the agreement of the customer to get an authorization token before accessing endpoint to confirm payment.

The root of authorization endpoint is provided in response from payment request creation.

Sandbox: https://api-sandbox.espace-prive.com/v2/authorize?response_type=code&scope=pisp&paymentResourceId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Real data:https://api.espace-prive.com/v2/authorize?response_type=code&scope=pisp&paymentResourceId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Connections are HTTPS-only, HTTP connections are refused. The current version of APIs can be retrieved in the API documentation.

You can request an authorization code by doing a GET including the following parameters:

client_id: UUID given through the developer portal (https://developer.espace-prive.com) when the app has been created.
state: internal state given by your app to uniquely identify the request
redirect_uri: call-back URL of the client app. This is the URL where the user will return to once the authorization process is ended. This redirectUrl should be one of the URLs you registered in the registration process.

Example :

https://api.espace-prive.com/v2/authorize?response_type=code&scope=pisp&paymentResourceId=35b4b013-8b5d-4490-991d-29ac41ef0b93&client_id=3466687a-7e3f-4c8f-b4a3-bf15fb11aaa4&state=12345&redirect_uri=https://my-callback-url

The authorization code request implies an authentication and signature given by the customer of the bank.

The following screen will be displayed to the customer:

The customer can choose his authentication flow but he must at least enter his identifier as used to access the internet banking.

Once authenticated, the customer is requested to sign the payment :

The customer must follow instructions regarding the authentication flow previously chosen to sign the payment.

At the end of the process, the customer is redirected to your redirect_uri communicated in the authorization code request with a set of parameters.

Example: successful response to activation code request

state: state sent by you to uniquely identify the request. You must check that the state corresponds to the state that you sent in your request
session_state: internal session state, not relevant to you
code: requested authorization code that will be used to request an access token (see below). The authorization code is valid for 60 seconds.

If the customer refuses to sign the payment, the parameters of the redirect_uri are:

state: state sent by you to uniquely identify the request
error: “access_denied”

Example: error response to authorization code request

http://my-callback-url/?error=access_denied&state=12345

3.2.1.2. PISP Access token Request

In order to get the access token, you are now able to call, through a POST request, the RMM’s token endpoint:

Sandbox:https://api-sandbox.espace-prive.com/v2/token
Real data:https://api.espace-prive.com/v2/token

Example: access token request

    POST
        https://api.espace-prive.com/v2/token
    Body (URL encoded):
        session_state=656d87dd-83ae-4fbc-8e66-84fab3e35135&code=1a87f856-a11b-4977-b220-b7ab6f833900.656d87dd-83ae-4fbc-8e66-84fab3e35135.22425f30-7d96-41c3-a1d1-922d0bbe44fd
        &grant_type=authorization_code
        &redirect_uri= my-callback-url
        &client_id=3466687a-7e3f-4c8f-b4a3-bf15fb11aaa4

Make sure to URL encode the body.

RMM responds with the requested tokens in JSON format:

access_token: access token provided by RMM
token_type: “bearer”
expires_in: access token lifetime, in seconds
refresh_token: refresh token that can be used for a future token renewal request
refresh_expires_in: refresh token lifetime, in seconds
session_state: internal session state, not relevant to you
not-before-policy: Open-ID connect information Not relevant to you.
scope: initial scope provided in the authorization code request

Example of response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJBdkpXM2NlmlvVlMxaVUzV0tJQm9FNFhqRjR3UDdkLVpPeTc4TnFHMG5vIn0.eyJqdGkiOiI4ZTYxM2E5Yi00OWQ4LTRiMYtYmVkOS1hYTViOWNhMTJiYTciLCJleHAiOjE2MzA1MTcxNzgsIm5iZiI6MCwiaWF0IjoxNjMwNTAyNzc4LCJpc3MiOiJodHRwczovL2Zob2d1aS1pLW5ld2I6ODk0My9hdXRoL3JlYWxtcy9mcm9uGVvIiwiYXVkIjoib3BlbmJhbmtpbmdfcmVzdF9hcGkiLCJzdWIiOiJmOmYzYWQwYzlhLWU0ZmItNZiYS04N2M1LTVlN2I4ZTMwMGJlNzowMDAwMDAwMDAwMjciLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiIxMDUyMjg2ZC03NTI1LTRmNzktOGU3OC1kZjUzY2YyZGU2MGYiLCJhdXRoX3RpbWUiOjE2MzA1MDI3NjgsINlc3Npb25fc3RhdGUiOiIyNTc5MzJiZC1kNjk3LTQ2ZTAYjg5YS0xNjc2MWNkYWQyZjciLCJhY3IiOiIxIiwic2NvcGUiOiJwaXNwIiwicGF5bWVudFJlc291cmNlSWQiOiIyMmNmNjg5MC02OWRlLTRlMTMtODExYy05NjY5YmQyYWE3YjciLCJzdWJzY3JpcHRpb25JZCI6IjAwMDAwMDAwMDAyNyJ9.EPDkUTL8m7WJJ1WwIOk8Nm-yfr_owxX024-Wlw8DeGVyc2sV0-Fng9beWm-YX8iQe9aGECfOANlWe462CNWKvzFfR9GdTU9bZ_MVk8qsWUlIR-wkCK7r0NHMZYqykTP_RcfhBgwcGVkUKSm61-lGJ2aWVmB5nJY2gz5pVS-VdMatmMryY9LoERyQsq683-cltt3XvxdUQjbZNvgHUiwzMQowtKcmVyfWm7Vak6FWBGfAOZOov3wOmcx5ETRPAPfKq8s57THBRcLciDcBO5_lYg1jDrtmqd_POmTbcajfdxe-a2YT-Im7gF_YxfevKnoqtM5x7KtB_mMvwJkrVeBQ",
  "expires_in": 60,
  "refresh_expires_in": 60,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1OGM5NzQOC1lMjllLTQ0NTMtODMwYi1jZjRmNzhhZThjZjMifQ.eyJqdGkiOiI5ZGZiMGUyOS1hZTMxLTQ3ZTAtYWRlYi1lZmM5MmQ2NDA1MDciLCJleHAiOjE2MzgyNzcwMDMIm5iZiI6MCwiaWF0IjoxNjMwNTAyNzc4LCJpc3MiOiJodHRwczvL2Zob2d1aS1pLW5ld2I6ODk0My9hdXRoL3JlYWxtcy9mcm9udGVvIiwYXVkIjoiaHR0cHM6Ly9maG9ndWktaS1uZXdiOjg5NDMvYXV0aC9yZWFsbXMvZnJvbnRlbyIsInN1YiI6ImY6ZjNhZBjOWEtZTRmYi00NmJhLTg3YzUtNWUYjhlMzAwYmU3OjAwMDAwMDAwMDAyNyIsInR5cCI6IlJlZnJlc2giLCJhenAiOiIxMDUyMjg2ZC03NTI1LTRmNzktOGU3OC1kZjUzY2YyZGU2MGYiLCJhdXRX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiIyNTc5MzJiZC1kNjk3LTQ2ZTAtYjg5YS0xNjc2MWNYWQyZjciLCJzY29wZSI6InBpc3AifQ.7vzcruxxfLTHqfL_DdX7EjHqv_ufj505AOXZAZa_Ro",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "257932bd-d697-46e0-b89a-16761cdad2f7",
  "scope": "pisp"
}

The access token must be used within the “Authorization” header, prefixed by the token type “Bearer”.

An access token is usually, for security reasons, valid for 5 minutes. The token lifespan can be changed by the bank without prior notice. The refresh token is useless for this case.

Refresh tokens should not be used in this case.

4. HTTP headers

4.1 Used request headers

In any request to Rothschild Martin Maurel, you must include the following HTTP headers.

Header related to the authorization token:

Authorization (String): access token provided by the bank at the end of the OAUTH flow

Header related to the connected customer (PSU):

PSU-IP-Address (String): IP Address of the customer terminal when connecting to your app
PSU-IP-Port (String): IP Port of the customer terminal when connecting to your app
PSU-HTTP-Method (String): HTTP Method used for the most relevant customer’s terminal request to your app
PSU-Date (String): Timestamp of the most relevant customer’s terminal request to your app
PSU-User-Agent (String): “User-Agent” header field sent by the customer terminal when connecting to your app
PSU-Referer (String): “Referer” header field sent by the customer terminal when connecting to your app
PSU-Accept (String): “Accept” header field sent by the customer terminal when connecting to your app
PSU-Accept-Charset (String): “Accept-Charset” header field sent by the customer terminal when connecting to your app
PSU-Accept-Encoding (String): “Accept-Encoding” header field sent by the customer terminal when connecting to your app
PSU-Accept-Language (String): “Accept-Language” header field sent by the customer terminal when connecting to your app
PSU-GEO-Location (String): The forwarded Geo Location of the corresponding HTTP request between customer and you, if available.
PSU-Device-ID (String): UUID (Universally Unique Identifier) for a device, which is used by the customer, if available UUID identifies either a device or a device dependent application installation. In case of installation identification this ID need to be unaltered until removal from device.

Header related to the signature [see also § HTTP Request Signing]:

Digest: SHA-256 hash of the body
Signature: http-signature of the request (cf https://www.ietf.org/archive/id/draft-cavage-http-signatures-10.txt). It contains four fields:
- keyId: must be filled with the QSEAL certificate URL followed by "_" (underscore) and the fingerprint of the certificate.
- signature: base 64 encoded digital signature, as described in RFC 4648, Section 4. The client uses the `algorithm` and `headers` signature parameters to form a canonicalized `signing string`. This `signing string` is then signed with the certificate associated with `keyId` and the algorithm corresponding to `algorithm`. The `signature` parameter is then set to the base 64 encoding of the signature.
- headers: list of HTTP headers included when generating the signature for the message. The list of required headers is given by the STET specification.
- algorithm: only RSA-SHA-256 currently supported Use value “rsa-sha256”.

Example of signature header:

Signature: keyId=https://path.to/myQsealCertificate_ 612b4c7d103074b29e4c1ece1ef40bc575c0a87e,algorithm="rsa-sha256",headers="date psu-date psu-geo-location x-requestid psu-referer psu-ip-port psu-accept authorization psu-accept-charset psu-accept-encoding psu-ip-address psu-user-agent psu-http-method psu-accept-language content-type user-agent digest content-length (request-target)", signature="tCYCZAGxVZLMlo87gHeXyPs2RkoNvOhCdsPvjkGhwkHlU1kT8xRBT3lybCT2UcjFrd2WroWaXexC3pYNYHJTwPN9HRV6dVXNRn3Ba2/BOA2n2g/+RELeAX318buwuEzQqAUOfci9d6d52X00+a5Dpb7h91T0zZuMBsPcxK6n2Sw="

Header related to the correlation of the request:

X-Request-ID: Unique correlation header provided by you to be set in a request and retrieved in the relevant response

Other standard header fields:

Date: HTTP's standard Date header (see RFC7231)
Content-Type: The Media type of the body of the request (used with POST and PUT requests).
Content-Length: The length of the request body in octets (used with POST and PUT requests).

Good to know

Since the generation of the signature input has to be an exact match, please read and follow the RFC draft closely
The header identifiers in the headers parameter must be in lower-case
The values in the (request-target) pseudo header (the HTTP verb, the URI) must be in lower-case
The (request-target) pseudo header does not contain parameters in case of a GET request
the list order of headers parameter is important, and MUST be specified in the order the HTTP header field-value pairs are concatenated together during signing
Strip any leading or trailing white space from the headers

4.2 Data exchange limitations

According to the article 36.5 of the RTS, AISPs are able to access information from payment accounts and associated payment transactions held by Rothschild Martin Maurel for the purposes of performing their services in either of the following circumstances:

Whenever the PSU (Payment Service User) is actively requesting such information. In this case, the access is unlimited and the AISP must communicate the PSU properties through the headers fields related to the PSU, as described in the previous paragraph (PSU-Date, PSU-IP-Address ?);
Where the PSU does not actively request such information, no more than four times a day (starting at 00:00 and ending at 24:00). The counter is incremented when the PSU properties are not provided in the request headers. Paging requests are not taken into account. If the AISP exceeds the limit, the request will be returned with a HTTP 429 error.

5. HTTP Request Signing

5.1. Principle

The process of signing a request is described in “Signing HTTP Messages' RFC draft version 10” issued by the IETF. The request signature needs to be sent in the 'Signature' HTTP header as described in the RFC.

Additional requirements from Rothschild Martin Maurel:

The additional header X-Request-ID, containing a unique request ID, is defined by you. Using a UUID is recommended.
We require the following headers required for every request: “date psu-date psu-geo-location x-requestid psu-referer psu-ip-port psu-accept authorization psu-accept-charset psu-accept-encoding psu-device-id psu-ip-address psu-user-agent psu-http-method psu-accept-language content-type digest content-length (request-target)". The request-target is a combination of the HTTP action verb and the request URI path.
The (optional) headers parameter normally allows for the client to specify which headers constitute the Authorization header's signature.

5.2. Signature components

Component	Corresponding header	Remark
(request-target)	Derived from the request	The request target is a combination of the HTTP action verb and the requests path. Note that this component is surrounded by parentheses. These are taken from the HTTP request, no additional header is needed.
date	Date	HTTP's standard Date header (see RFC7231) Mandatory. Important: We enforce a strict time frame within which the request has to be issued. If the Date header's timestamp diverges by more than 5 minutes, the request will be considered invalid and rejected. Example: 2019-02-08T09:37:52.375+02:00
digest	Digest	Digest of the post body; the SHA-256 hash of the body. Example: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
x-request-id	X-Request-ID	A unique identifier specified by you. Example: 06925169-742b-46c2-bf0c-fd10020d33e4
psu-ip-address	PSU-IP-Address	IP address of the customer terminal when connecting to your app
psu-ip-port	PSU-IP-Port	IP port of the customer terminal when connecting to your app
psu-http-method	PSU-HTTP-Method	HTTP method for the most relevant customer’s terminal request
psu-date	PSU-Date	Timestamp of the most relevant customer’s terminal request
psu-user-agent	PSU-User-Agent	“User-Agent” header field sent by the customer
psu-referer	PSU-Referer	“Referer” header field sent by the customer
psu-accept	PSU-Accept	“Referer” header field sent by the customer
psu-accept-charset	PSU-Accept-Charset	“Accept-Charset” header field sent by the customer
psu-accept-encoding	PSU-Accept-Encoding	“Accept-Encoding” header field sent by the customer
psu-accept-language	PSU-Accept-Language	“Accept-Language” header field sent by the customer
psu-geo-location	PSU-GEO-Location	The forwarded Geo location of the customer
psu-device-id	PSU-Device-ID	UUID of the customer’s device UUID identifies either a device or a de vice dependent application installation In case of installation identification, this ID needs to be unaltered until removal from the customer’s device.
content-type	Content-Type	The Media type of the body of the request (used with POST and PUT requests)
content-length	Content-Length	The length of the request body in octets (used with POST and PUT requests)

Rem Header fields that are not present in the request must be removed from the list.

Note that responses sent back by Rothschild Martin Maurel are not signed.

6. Sandbox

The sandbox environment enables you to test your application. The sandbox environment contains the same services as the real data environment but with dummy data.

This allows you to try out our APIs and get responses with dummy data from our API.

6.1. Prerequisites

Before you can get started with the sandbox, you must communicate your QWAC and QSEAL certificates through the developer portal https://developer.espace-prive.com.

6.2. The supported flows

The sandbox currently supports the following flows:

"Client credentials grant flow" to get an application access token (PISP)
Consent granting: "Authorization code grant flow" to create a customer access token (AISP & CBPII), including the SCA process
PSD2 AISP services to retrieve customer accounts, balances, transactions, user identity and beneficiaries
PSD2 PISP to initiate payments and standing orders, without the SCA process
PSD2 CBPII to check the funds coverage

6.3. Data available for Sandbox requesting

All information in the sandbox can be retrieved from one single dummy customer subscription, having the following properties:

Subscription id (for user identification): always use SANDBOX1 as "Identifiant"
Password (for user authentication): use 1111 as "Mot de passe" - See picture below

SMS code for signatures: use 111111 as "code SMS de confirmation" - See picture below

List account transactions: use the account FR7613369000077552140301326. There are some transactions for this account between July 9th, 2019 and Sept 15th, 2019. Other accounts belonging to the subscription have no transactions.
Transactions on the credit card are available between April 20th, 2019 and July 19th, 2019
Account for payments: FR7613369000077552140301326

Using other properties will lead to an error message.