Get Started

1. Welcome

Welcome to the MyPartnerBank Developer Portal. This portal will allow you to access the MyPartnerBank 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.mypartnerbank.fr/.

We base our APIs on current industry standards and best practices MyPartnerBank 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 MyPartnerBank. 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, MyPartnerBank 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 MyPartnerBank APIs, you must register yourself and your company to the MyPartnerBank developer portal [https://developer.mypartnerbank.fr/].

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 MyPartnerBank developer portal: https://developer.mypartnerbank.fr/ and sign up (link at the top right corner).

You must provide the following information:

  • Your company name
  • Your PSP Authorization identifier (starting with PSD...)
  • Your first name and 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. Explore the APIs

There are currently three groups of APIs For the detailed information of each API, see the API documentation guide available on this portal under the menu entry "API Documentation"..

  • 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 confirmation: it allows to check the availability of funds on a given account or card.

2.4. Create your app

Now you are ready to go:

  1. Create your app in the portal: this requires the name of your app.
  2. 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.

  1. 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
  2. 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
  3. Ensure that your application is subscribed to the API with the roles you want to request from the customer.
  4. 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.5. 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 MyPartnerBank.

2.5.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.5.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.5.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:

  1. The client (your app) initiates the flow and requests an authorization code to MyPartnerBank. If the end-customer gives his/her consent, a short lifespan authorization code is returned to the client.
  2. With the authorization code, the client can ask the access and refresh tokens to MyPartnerBank. 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 MyPartnerBank should look like this:

  1. The customer instructs you to make a connection between your app and MyPartnerBank
  2. Your app redirects the customer to MyPartnerBank
  3. The customer will authenticate itself in the secured and trusted MyPartnerBank environment
  4. The consent request is presented to the customer
  5. The customer grants you access in the secured and trusted MyPartnerBank environment by signing the consent request
  6. 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:

  1. MyPartnerBank 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.
  2. 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.

MyPartnerBank’s OAuth 2.0 endpoint is:

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.mypartnerbank.fr/) 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.mypartnerbank.fr/v1/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 must enter:

  • his identifier as used to access the internet banking
  • his password

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

A SMS code is sent by MyPartnerBank to the customer (without digipass) who must key it in to sign the consent request. User with Digipass must enter the digipass code.

 

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 MyPartnerBank’s token endpoint:

Example: access token request (Sandbox)

POST https:// api-sandbox.mypartnerbank.fr/v1/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.

MyPartnerBank responds with the requested tokens in JSON format:

  • access_token: access token provided by MyPartnerBank
  • 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 MyPartnerBank 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 MyPartnerBank customer.

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

Example: access token refresh (Sandbox)

POST https:// api-sandbox.mypartnerbank.fr/v1/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:

  1. The customer is checking out his/her purchase basket and is selecting your app as payment means
  2. The customer gives MyPartnerBank as bank holding his/her account
  3. Your app sends the details of the payment transaction to MyPartnerBank via the Payment Initiation API
  4. MyPartnerBank will provide an URL to the PISP, which can be used by the customer to sign the payment transaction
  5. Your app redirects the customer to MyPartnerBank by means of the provided URL
  6. The customer will authenticate himself/herself in the secured and trusted MyPartnerBank environment
  7. The customer can simply select a debit account out of the list of his/her payment accounts
  8. MyPartnerBank performs the regular checks as for payments initiated via MyPartnerBank customer channels, including a check on sufficient balance
  9. The customer authorizes the payment in the secured and trusted MyPartnerBank environment
  10. In case of positive outcome of the regular checks and a successful authorization, MyPartnerBank sends an “OK” back to the PISP and starts processing the payment transaction
  11. 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 MyPartnerBank’s token endpoint:

Example: access token request (Sandbox)

POST https:// api-sandbox.mypartnerbank.fr/v1/token
Body (URL encoded):

    &grant_type= client_credentials

    &scope=pisp

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

Make sure to URL encode the body.

MyPartnerBank responds with the requested tokens in JSON format:

  • access_token: access token provided by MyPartnerBank
  • 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": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhRVJkcVU3a3dtOE4zbFAweXVsdm81Y3Job19kOWpkMFhUY1o0cFZZejNVIn0.eyJqdGkiOiIyYTg2OTY2Zi0zNzU5LTQxZjAtYTc0ZS03ZTZjYmU2ODVjMjQiLCJleHAiOjE1NzE0MTU1MDUsIm5iZiI6MCwiaWF0IjoxNTcxNDAxMTA1LCJpc3MiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstaWF0LWJlc3Y6ODQ0My9hdXRoL3JlYWxtcy9mcm9udGVvLXNhbmRib3giLCJhdWQiOiJvcGVuYmFua2luZ19yZXN0X2FwaSIsInN1YiI6ImY6NmZhZGQ5MGMtNDQ3Ni00NmEzLTkyMTktNzIzY2JiZjI2MzM1OlNBTkRCT1gxIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiM2NlM2FiMDUtMTBjZS00ZDk0LTgyNDctOTFjNzVmMTRjMGNlIiwiYXV0aF90aW1lIjoxNTcxNDAxMTA1LCJzZXNzaW9uX3N0YXRlIjoiYTkwOTU4NDQtMjhlOS00ZmQwLWE3NDktMGY0NTdmY2UxMWYwIiwiYWNyIjoiMSIsInNjb3BlIjoiYWlzcCIsImNsaWVudE51bWJlciI6IjQ2MDA0Iiwic3Vic2NyaXB0aW9uSWQiOiJTQU5EQk9YMSJ9.mMeCQZOfw6fFx9D2uVg27cgyEUOMtl10k7CovRmLSlSjQdueOXBkq8guwz468IbtbyGg6sSr6QgMt39DQ8GnQdXh5mxnPNNdkh-iupG-AW_JiXa8F89LjEXnfFtluCeiHDRiJvKM4jzPcbTrT9UwTppYN9W5j6jT-jGjmQKGDKOmLArDQlMiTBB4u2gPt1x_0KwePSwPXa2Qo3D5vLAJDgg26aCovBT-6fCScB5QopX_9cfs4hptA3A59cIsoCrLuqznNF5Eba5sXILkFByrPXywhrLv_zUTpKZSO8P8LwnjPZWfvgAuugnarLD3_p9Elki8zScubc2sNPWi-ORJUA",

"expires_in": 300,

"refresh_expires_in": 7776000,

"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyZTI5NWFjOC1kOGMxLTRjMmUtOTM0Ni02MTYyZDM0MGI2MTEifQ.eyJqdGkiOiJkZmIyZjY2OC1iNTFjLTRhNjItODJjMC02OThkOTAzYWNjYmMiLCJleHAiOjE1NzkxNzcxMDUsIm5iZiI6MCwiaWF0IjoxNTcxNDAxMTA1LCJpc3MiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstaWF0LWJlc3Y6ODQ0My9hdXRoL3JlYWxtcy9mcm9udGVvLXNhbmRib3giLCJhdWQiOiJodHRwczovL2Zyb250ZW8ta2V5Y2xvYWstaWF0LWJlc3Y6ODQ0My9hdXRoL3JlYWxtcy9mcm9udGVvLXNhbmRib3giLCJzdWIiOiJmOjZmYWRkOTBjLTQ0NzYtNDZhMy05MjE5LTcyM2NiYmYyNjMzNTpTQU5EQk9YMSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiIzY2UzYWIwNS0xMGNlLTRkOTQtODI0Ny05MWM3NWYxNGMwY2UiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJhOTA5NTg0NC0yOGU5LTRmZDAtYTc0OS0wZjQ1N2ZjZTExZjAiLCJzY29wZSI6ImFpc3AifQ.q5WzJaokN9HjRnK1BbBUEDry77ltjsSEXKd-NUu-fwU",

"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.

 

4. HTTP headers

4.1 Used request headers

In any request to MyPartnerBank, 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:
    • 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 MyPartnerBank 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 MyPartnerBank:

  • 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 MyPartnerBank 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.mypartnerbank.fr/.

6.2. The supported flows

The sandbox currently supports the following flows:

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

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 "Numéro d'abonné"
  • Password (for user authentication): use 1111 as "Code secret" - See picture below
  • SMS code for signatures: use 111111 as "Code SMS" - See picture below
  • List account transactions: use the account FR7643659100000777700100119. There are some transactions for this account between July 13th, 2018 and May 1st, 2019. Other accounts belonging to the subscription have no transactions.
  • Account for payments: FR7643659100000777700100119

Using other properties will lead to an error message.