Get account and transaction information

This tutorial presents how 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.

Prerequisites​

Before you begin, ensure that you have:

• Registered your application with the accounts scope in the Developer Portal
• Obtained a sandbox/production client_id from the Developer Portal
• Obtained sandbox/production transport.pem and signing.pem certificates from the Developer Portal or from a QTSP issuing body
• Uploaded in the Developer Portal the jwks_url that is specific to your signing.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:

The response returns a new client credentials access token, with its expiry (expires_in) provided in seconds:

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

You use this token to:

• Update your application.
• Create an account access consent in the next step.

2. Create an account access consent​

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

curl --location --request POST 'https://oba-auth.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-auth.revolut.com/account-access-consents"
  },
  "Meta": {
    "TotalPages": 1
  }
}

To check all the supported permissions and the dependencies:

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.

Create a JWT request parameter with the header and body format presented below, 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.

Header:

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

Body:

{
  "response_type": "code id_token",
  "client_id": "<insert client_id>",
  "redirect_uri": "<insert redirect_uri>",
  "aud": "https://oba-auth.revolut.com",
  "scope": "accounts",
  "state": "<insert state>",
  "nbf": <insert nbf>,
  "exp": <insert exp>,
  "claims": {
    "id_token": {
      "openbanking_intent_id": {
        "value": "<insert ConsentId>"
      }
    }
  }
}

4. Get consent from the user​

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

A sample authorisation URL looks like this:

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

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

5. Exchange the authorisation code for an access 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 and Transactions endpoints:

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:

The response returns a new access token, with its expiry (expires_in) provided in seconds, and a refresh token, with its expiry (refresh_token_expires_at) provided as a timestamp:

{
  "access_token":"oa_sand_tP1Nofi1ixsRfBmVBtVPdIVN0J5x91imqmheQIWTS5s",
  "access_token_id":"3d3ef8a1-f920-4d6d-9106-e7fcf350125c",
  "token_type":"Bearer",
  "expires_in":3599,
  "id_token":"<JWT id_token>",
  "refresh_token":"oa_sand_mV1NoTBtVPdfi1ixsRfBmS5sqmheQIWIVN0J5x91itP",
  "refresh_token_expires_at":1759051135
}

6. Get the list of accounts​

Once you have a valid 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.

curl -X GET https://oba-auth.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-auth.revolut.com/accounts/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

For more details about this call:

Usage of the Refresh Token​

When the access token expires, you won't be able to access the Accounts and Transactions endpoints.

To regain access, you must first request a new access token using the refresh token (returned in step 5), your Client ID (returned in substep 7 of Upload your certificate), and your certificate and key.

Get a new access token​

To request a new access token, make a request to the /token endpoint with grant_type=refresh_token and a valid refresh token:

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=refresh_token' \
--data-urlencode 'client_id=<your client_id>' \
--data-urlencode 'refresh_token=<your refresh_token>'

Response:

The response returns a refreshed access token, with its expiry (expires_in) provided in seconds:

{
  "access_token":"oa_prod_fBmVQP91imqmhetP1NofixsBtVIVN0J5xRi1IdWTS5s",
  "token_type":"Bearer",
  "expires_in":3599
}

What's next​

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