1. Welcome
Welcome to the Moneytrans Developer Portal. This portal will allow you to access the Moneytrans 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://pac-developer.moneytrans.eu.
We base our APIs on current industry standards and best practices. Moneytrans 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 Moneytrans. 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, Moneytrans uses 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 Moneytrans APIs, you must register yourself and your company to the Moneytrans developer portal [https://pac-developer.moneytrans.eu].
2.1. Prerequisites
Before starting, you must have proceeded the following:
- Be registered as a TPP by your National competent authority (NBB in Belgium, ACPR in France, ...) 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 Moneytrans developer portal: https://pac-developer.moneytrans.eu
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. 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 up.
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 an user, remove an user from the team or leave your
team.
- Pending requests: When a new developer is trying to join your team, you will receive a mail 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. A mail 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 available on this portal under the menu entry "API Documentation".
- XS2A: Access to Accounts, including balances, beneficiaries and transactions.
- Payment Initiation: it includes single SEPA credit transfers (standing orders and bulks are not
taken in charge).
- Funds confirmation: 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.
- 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 Moneytrans.
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 Moneytrans. 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 Moneytrans. 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 Moneytrans should look like this:
- The customer instructs you to make a connection between your app and Moneytrans
- Your app redirects the customer to Moneytrans
- The customer will authenticate itself in the secured and trusted Moneytrans environment
- The consent request is presented to the customer
- The customer grants you access in the secured and trusted Moneytrans 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:
- Moneytrans 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).
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.
Moneytrans’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://pac-developer.moneytrans.eu)
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://pac-api-sandbox.moneytrans.eu/v1/authorize?response_type=code&scope=aisp&client_id=7846687a-7e3b-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 email address as identifier
- his password
Once authenticated, the customer is requested to sign the consent granted to the Third party Provider:
The customer must key in the Google Authenticator code 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 Moneytrans’ token
endpoint:
Example: access token request (Sandbox)
POST https://pac-api-sandbox.moneytrans.eu/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.
Moneytrans responds with the requested tokens in JSON format:
- access_token: access token provided by Moneytrans
- 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 Moneytrans 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 Moneytrans customer.
You can ask a new access token with your refresh token. The corresponding endpoint is:
Example: access token refresh (Sandbox)
POST https://pac-api-sandbox.moneytrans.eu/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:
- The customer is checking out his/her purchase basket and is selecting your app as payment means
- The customer gives Moneytrans as bank holding his/her account
- Your app sends the details of the payment transaction to Moneytrans via the Payment Initiation API
- Moneytrans 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 Moneytrans by means of the provided URL
- The customer will authenticate himself/herself in the secured and trusted Moneytrans environment
- The customer can simply select a debit account out of the list of his/her payment accounts
- Moneytrans performs the regular checks as for payments initiated via Moneytrans customer channels, including a check on sufficient balance
- The customer authorizes the payment in the secured and trusted Moneytrans environment
- In case of positive outcome of the regular checks and a successful authorization, Moneytrans 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 Moneytrans’ token endpoint:
Example: access token request (Sandbox)
POST https://api-sandbox.moneytrans.eu/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.
Moneytrans responds with the requested tokens in JSON format:
- access_token: access token provided by Moneytrans
- 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": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyN2h1eC1iWm5mdUNENzBPa1U0NDhpTUdRYl9vdzZFalpjdV9PQjVpam1jIn0.eyJqdGkiOiIxOTQ0MjkxYS1iM2MwLTQ0MTEtYjlhNC0wN2QyOGNhZDcwODIiLCJleHAiOjE1NzEyNDY3MDAsIm5iZiI6MCwiaWF0IjoxNTcxMjMyMzAwLCJpc3MiOiJodHRwczovL2YyYi1pYXQtbXRyOjg0NDMvYXV0aC9yZWFsbXMvZnJvbnRlby1zYW5kYm94IiwiYXVkIjoib3BlbmJhbmtpbmdfcmVzdF9hcGkiLCJzdWIiOiJmOmViMDk5YWY2LWExMjAtNDBlMC1hOTIwLTU4ZTM3Y2ZkNjI2MjphcGkuc2FuZGJveC50ZXN0QG1vbmV5dHJhbnMuZXUiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiIyZTk0NjU0MC1hNWViLTQ2OGQtYjM5YS02MTE3Yjc3YWUzMTUiLCJhdXRoX3RpbWUiOjE1NzEyMzIyOTksInNlc3Npb25fc3RhdGUiOiI2ZTQ5MTQ5ZC1iOTI1LTRmOTAtYWE3NC0xNTFiNzljODI1NWYiLCJhY3IiOiIxIiwic2NvcGUiOiJhaXNwIiwiY2xpZW50TnVtYmVyIjoiYXBpLnNhbmRib3gudGVzdEBtb25leXRyYW5zLmV1Iiwic3Vic2NyaXB0aW9uSWQiOiJhcGkuc2FuZGJveC50ZXN0QG1vbmV5dHJhbnMuZXUifQ.GC2kDlEZ7nRfGbtjXGOIK0fDMgXFeY_d99a8XPaxj0fMtF7eW4Jx3nuCPr15SLEBJ_gWA6OLymgOeKssbnqbygLRwlO3-8b-czfLos_czYWz3RNGFu9Q-YvhJPUv1GjiXspsANqaNiFPigRPxre8_prqUAFuU2iIfwspksItkL_QO7GEDgvh1gAwCjoqHKjxpABG_wbzY09KriV0y_FfH5MiO_CL0VfwvgBxWcQ-eKCKldfmDdlMWX5hp9Pezfh8NnJ14gHTqiN6Rho8V1Ql1PUPZo38gceA0b_AOxqcTPKQdlnJCQK4-cfXKlmfKyoum4vdUg0lFcxCQu1NCzRYIA",
"expires_in": 300,
"refresh_expires_in": 7776000,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiMjI0NDZlOS05NTE3LTRhNGQtOTRlYS1lYWY5MzFiMjVkNmYifQ.eyJqdGkiOiJiYjY4OWQ2ZS0xM2QyLTQ1MzEtYjdmOC02YzA2MDJmZDJjYzYiLCJleHAiOjE1NzkwMDgyOTksIm5iZiI6MCwiaWF0IjoxNTcxMjMyMzAwLCJpc3MiOiJodHRwczovL2YyYi1pYXQtbXRyOjg0NDMvYXV0aC9yZWFsbXMvZnJvbnRlby1zYW5kYm94IiwiYXVkIjoiaHR0cHM6Ly9mMmItaWF0LW10cjo4NDQzL2F1dGgvcmVhbG1zL2Zyb250ZW8tc2FuZGJveCIsInN1YiI6ImY6ZWIwOTlhZjYtYTEyMC00MGUwLWE5MjAtNThlMzdjZmQ2MjYyOmFwaS5zYW5kYm94LnRlc3RAbW9uZXl0cmFucy5ldSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiIyZTk0NjU0MC1hNWViLTQ2OGQtYjM5YS02MTE3Yjc3YWUzMTUiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI2ZTQ5MTQ5ZC1iOTI1LTRmOTAtYWE3NC0xNTFiNzljODI1NWYiLCJzY29wZSI6ImFpc3AifQ.ZTfZC18eM80IEmvG4MkCzKXMoi2FH-muuWqMQt29hUU",
"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 Moneytrans, 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_3466687a-7e3f-4c8f-b4a3-bf15fb11aaa4,
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 Moneytrans 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 Moneytrans:
- 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 Moneytrans 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://pac-developer.moneytrans.eu.
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 without the SCA process (standing orders and bulks are not taken in charge)
- 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:
- Email address (for user identification): always use api.sandbox.test@moneytrans.eu
- Password (for user authentication): use OpenBanking?9
- Google authenticator code for signatures: use 111111
- Account for payments: BE24500001005338. There are some transactions for this
account between May 31th, 2017 and June 18th, 2019. Other accounts belonging to the subscription have no
transactions.
Using other properties will lead to an error message.