Get account and transaction information

This tutorial walks you through the steps to pull the data of a user's account from the /accounts endpoint.

Similar steps apply to all the Accounts and Transactions endpoints, therefore, after you complete this tutorial, you will know how to use all those endpoints.

See the Open Banking API: Account and Transactions for all the available endpoints.

Before you begin, ensure that you have:

• Registered your application with the accounts scope in Developer Portal
• Obtained a sandbox/production client_id from Developer Portal
• Obtained a sandbox/production transport.pem certificate from Developer Portal or QTSP issuing body
• Uploaded the jwks_url in Developer Portal that is specific to your transport.pem certificate

1. Generate a client credentials token​

Request an access token for client credentials using the /token endpoint and the client_credentials grant type:

curl --cert transport.pem --key private.key \
--location --request POST 'https://oba-auth.revolut.com/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=accounts' \
--data-urlencode 'client_id=<your client_id>'

Response:

{
  "access_token":"<JWT client credentials>",
  "token_type":"Bearer",
  "expires_in": 2399
}

You use this token to:

• Update your application.
• Create a consent in the next step.

2. Create a consent​

Create a consent:

curl --location --request POST 'https://oba.revolut.com/account-access-consents' \
--header 'x-fapi-financial-id: 001580000103UAvAAM' \
--header 'Authorization: Bearer <insert JWT client credentials from step 1.>' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "Data": {
        "Permissions": [
            "ReadAccountsBasic",
            "ReadAccountsDetail"
        ],
        "ExpirationDateTime": "2020-12-02T00:00:00+00:00",
        "TransactionFromDateTime": "2020-09-03T00:00:00+00:00",
        "TransactionToDateTime": "2020-12-03T00:00:00+00:00"
    },
    "Risk": {}
}'

Response:

{
  "Data": {
    "Status": "AwaitingAuthorisation",
    "StatusUpdateDateTime": "2020-11-05T16:07:46.506182Z",
    "CreationDateTime": "2020-11-05T16:07:46.506182Z",
    "TransactionToDateTime": "2017-12-03T00:00:00+00:00",
    "ExpirationDateTime": "2021-05-02T00:00:00+00:00",
    "Permissions": [
      "ReadAccountsBasic",
      "ReadAccountsDetail"
    ],
    "ConsentId": "d19ec758-22fd-4f34-9ad4-7437f8628987",
    "TransactionFromDateTime": "2017-05-03T00:00:00+00:00"
  },
  "Risk": {},
  "Links": {
    "Self": "https://oba.revolut.com/account-access-consents"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Create a consent for specific permissions using the /account-access-consents endpoint.

In this tutorial, you create a consent for the following permissions:

• ReadAccountBasic
• ReadAccountsDetail

To check all the supported permissions and the dependencies, see the Open Banking API: Create an account access consent.

3. Create a JWT URL parameter​

After you create a consent, you need the user to authorise the consent so that you can access the data on their behalf.

Header:

{
  "alg": "PS256",
  "kid": "<insert kid>"
}

Body:

{
  "response_type": "code id_token",
  "client_id": "<insert client_id>",
  "redirect_uri": "<insert redirect_uri>",
  "scope": "accounts",
  "claims": {
    "id_token": {
      "openbanking_intent_id": {
        "value": "<insert ConsentId>"
      }
    }
  }
}

Create a JWT request parameter with the header and body format on the right, signed by your signing certificate's private key. This signature is validated using the JWKs endpoint that you specified during the registration of your application.

4. Get the consent from user​

Sample URL:

https://oba.revolut.com/ui/index.html?response_type=code%20id_token&scope=accounts&redirect_uri=<insert redirect URL>&client_id=<insert client_id>&request=<insert JWT from step 3.>&state=example_state

Redirect the user to the authorisation URL with the following parameters. Make sure they are URL-encoded.

Sample redirect after successful response:

https://example.com/?code=oa_sand_sPoyVs-oMhyR36j5N-ZEVLfK9rQWPNssgIQqsOFZQ-c&id_token=<JWT id_token>&state=example_state

On successful completion of the authorisation flow, you receive an authorisation code (code) as a URL parameter in the redirect.

Check the response example on the right to see what the code looks like.

5. Exchange authorisation code for access token​

Exchange for access token:

curl  --key private.key --cert transport.pem \
--location --request POST 'https://oba-auth.revolut.com/token' \
--header 'Content-Type:application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=<insert auth_code>'

Response example for UK-based TPPs:

{
  "access_token":"oa_sand_tP1Nofi1ixsRfBmVBtVPdIVN0J5x91imqmheQIWTS5s",
  "access_token_id":"3d3ef8a1-f920-4d6d-9106-e7fcf350125c",
  "token_type":"Bearer",
  "expires_in":1576800000,
  "id_token":"<JWT id_token>"
}

Response example for EEA TPPs:

{
  "access_token":"oa_sand_tP1Nofi1ixsRfBmVBtVPdIVN0J5x91imqmheQIWTS5s",
  "access_token_id":"3d3ef8a1-f920-4d6d-9106-e7fcf350125c",
  "token_type":"Bearer",
  "expires_in":7775999,
  "id_token":"<JWT id_token>"
}

After the user authorises your consent, you use the /token endpoint with grant_type=authorization_code to get the access token that you can use to access the Accounts API.

access_token_id is used in conjunction with the token webhook to identify tokens where the user has revoked their consent.

6. Get a list of accounts​

Get a list of accounts:

curl -X GET https://oba.revolut.com/accounts \
--header 'Authorization: Bearer <insert access_token from step 5.>' \
--header 'x-fapi-financial-id: 001580000103UAvAAM'

Response:

{
  "Data": {
    "Account": [
      {
        "AccountId": "A1086696-D134-472D-B83E-A3F4D201C058",
        "Currency": "GBP",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Bills",
        "Account": [
          {
            "SchemeName": "UK.OBIE.SortCodeAccountNumber",
            "Identification": "80200110203345",
            "Name": "Mr Kevin",
            "SecondaryIdentification": "00021"
          }
        ]
      }
    ]
  },
  "Links": {
    "Self": "https://oba.revolut.com/accounts/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

After you generate this access token, you can use it to send requests to the API. Make a call to the /accounts endpoint to retrieve a list of the user's accounts.

Congratulations! You have successfully made your first API request to one of our Accounts and Transactions endpoints.

What's next​

• See the Open Banking API: Account for full details on different permissions and endpoints.
• See Tutorials: Initiate your first payment for building your integration to our payments endpoints.