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:
accounts
scope in Developer Portalclient_id
from Developer Portaltransport.pem
certificate from Developer Portal or QTSP issuing bodyjwks_url
in Developer Portal that is specific to your transport.pem
certificateRequest 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:
When your token expires and you need a new one, repeat this procedure to generate a new token.
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.
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.
The values of client_id
, redirect_uri
, kid
, and scope
should correspond to those for your specific application and consent request.
The value of openbanking_intent_id
is the value of the ConsentId
field generated from the previous step.
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.
Parameter | Description | Required |
---|---|---|
response_type | Always set to code id_token . | yes |
client_id | The client ID for your application. | yes |
redirect_uri | One of the redirect URIs that you defined during the application creation. | yes |
scope | The scope that you are requesting, for example, accounts or payments . | yes |
request | The encoded JWT generated from the previous step. | yes |
response_mode | If set to fragment parameters will be passed in fragment section of redirect URI. Otherwise, parameters are passed in URI query. Passing parameters in fragment is considered to be more secure. | no |
state | OAuth parameter that lets you restore the state of the application after redirection. If provided, this value is returned in the redirect URI. | no |
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.
The code
is valid only for two minutes.
For Third Party Providers (TPPs) with an eIDAS certificate, the following changes will apply from 25 July 2023 in accordance to the Commission Delegated Regulation (EU) 2022/2360 of 3 August 2022:
For UK-based TPPs, we will continue to issue long-lived tokens valid for 50 years.
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.
The value of auth_code
is the authorisation code (code
) generated from the previous step.
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.