Skip to content
Last updated

Quickstart

This quickstart will guide you through getting a user's account information through the PSD2 channel of the PSD2 API .

Steps we will go through:

Prerequisites

Before you begin, make sure you have completed the Getting Started guide — you'll need your CLIENT_ID and CLIENT_SECRET.

Gain access

For this we will use the CLIENT_ID and CLIENT_SECRET which you can obtain by contacting your contact person at Aritma.

We will also use two scopes:

  • banking.channel.psd2 allows the user to select a bank available through PSD2
  • banking.ais.read gives us access to query account information using a consent
cURL
curl -i -X POST https://id.dev.aritma.io/connect/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d grant_type=client_credentials \
    -d client_id=$CLIENT_ID \
    -d client_secret=$CLIENT_SECRET \
    -d scope=banking.channel.psd2%20banking.ais.read
{
  "access_token": "\<token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "banking.channel.psd2 banking.ais.read"
}

The response will contain your access token, which will be used in the authorization header for all subsequent request.

Authorization: Bearer \<token>

To connect to the account information of your first user we must first create a new consent.

Note:

A consent is what we use to connect to the bank of the end-user.

cURL
curl -i -X POST https://banking.dev.aritma.io/api/consents \
-H "Content-Type: application/json" \
-H "Authorization: Bearer \<token>" \
-d '{"channelType":"psd2"}'
{
  "consentId": "\<consentId>",
  "redirectUrl": "https://banking.dev.aritma.io/consent/c/s/PeECf1dnHys",
  "status": "Created"
}

The response contains a consentId which you need to store in order to query account information later on. It also contains a redirectUrl which you'll need to redirect your user to.

Note:

The redirectUrl is only usable once.

It's time to wait for your user to complete the consent. If you specified a success url in the redirectSettings when you created the consent, we will redirect the user there when the consent is completed. You can also use the event endpoint to subscribe to changes in the consent status.

Let's verify the status of the consent by querying the API.

cURL
curl -i https://banking.dev.aritma.io/api/consents/\<consentId> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer \<token>"
{
  "consentId": "\<consentId>",
  "status": "Authorized",
  "additionalData": {
    "expiresAtUtc": "2023-06-27T08:20:40.348Z"
  }
}

The response shows us two things:

  • The consent status is Authorized which means that it's ready for use
  • It has an expiration date which tells us how long we can use it
Note:

Although a consent normally last for 90 days, the user has access to withdraw the consent at any time. Keep this in mind when designing your integration.

Retrieve Account Information

Now that the consent is ready for use, we can use it to retrieve the bank accounts of the user. We do so by setting the header Consent-ID to the consentId we created earlier.

cURL
curl -i https://banking.dev.aritma.io/api/accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer \<token>" \
-H "Consent-ID: \<consentId>"
{
    "accounts": [
        {
            "id": "1",
            "iban": "FR7612345987650123456789014",
            "bban": "BARC12345612345678",
            "name": "Account 1",
            "displayName": "Account 1",
            "balances": []
        },
        {
            "id": "2",
            "iban": "FR7612345987650123456789017",
            "bban": "BARC12345612345679",
            "name": "Account 2",
            "displayName": "Account 2",
            "balances": []
        }
    ]
}

The response contains the bank accounts of our user

Note:

PSD2 has strict rate-limits when querying account information without a user present. To query information with a user present, set the request header PSU-IP-Address to the IP-Address of the user.

Previous page
Next page