Redeeming an Access Token

The account information access permissions you specify in your access token request are reflected in the access token generated. Consequently, if you don't ask for access to a resource type in your access token request, it won't be granted in the access token.

Keeping that in mind, the server-side call forAccessToken() is used to get the object — called a RepresentableClosedInterface representing the part of a Token member's account information that can be accessed based on the permissions granted in an access token.representing your customer-user. You can then make getResource calls on the Representable object— getAccounts(), getBalances(), getTransactions(), getStandingOrders() and/or getTransferDestinations() — depending on the resource permissions granted in the access token.

A getAccounts() call retrieves a list of accounts the customer holds in the selected bank. Similarly, getBalances() fetches the current balance of each listed account. getTransactions() for a specified account returns a paged listClosedUsed for managing a list of remotely paged (lazy-loaded) objects beginning at an offset (place in the list). of transactions made to/from that account, which can be filtered by booking date — startDate and/or endDate. A getTransferDestinations() call fetches the beneficiary accounts associated with each transaction.

Fields in a Access Token Redemption
Field Description Required/ Optional
balance This is the access object; contains the account information requested Required
customerInitiated Boolean value. Set it to true if the customer initiates the access to bypass the Token PlatformClosedOperated and maintained by Token to provide turnkey PSD2 and OBIE compliance for easy and secure TPP connectivity with banks offering payment initiation and account information services. cache. Optional
grantee TPP that has been granted information access by grantor Required
grantor The customer-user granting access consent to the TPP (grantee) Required
refId Reference identifier for the token; not to be confused with requestId. This field is typically used by the TPP to de-duplicate requests. If not provided, Token generates a random string as the refId. Required
tokenId Identifies the access token to be redeemed Required

Get Balances

For an account balance query, here's the quick form:

public static Money redeemBalanceAccessToken(Member grantee, String tokenId) {

 

    // specifies whether the request originated from a customer

    boolean customerInitiated = true;

 

    // access grantor's account list by applying

    // access token to the grantee client

    Representable grantor = grantee.forAccessToken(tokenId, customerInitiated);

    List<Account> accounts = grantor.getAccountsBlocking();

 

    // get the data we want — here, STANDARD is the key-pair level for the grantor

    Money balance = accounts.get(0).getBalanceBlocking(STANDARD).getCurrent();

 

    return balance;

}

Tip: Because the forAccessToken method lets you specify which access token to apply to access account information, you should establish your own server-side mechanism to correlate access tokens with users. For more on member key pairs, see the onboarding topic on managing keys.

Get Transactions

To get a paged list of transactions for one or more customer-user accounts:

public static List<Transaction> redeemTransactionsAccessToken(Member grantee, String tokenId) {

 

    // Specifies whether the request originated from a customer

    boolean customerInitiated = true;

 

    // access grantor's account list by applying

    // access token to the grantee client

    Representable grantor = grantee.forAccessToken(tokenId, customerInitiated);

    List<Account> accounts = grantor.getAccountsBlocking();

 

    // get the 10 most recent transactions —

    // here, STANDARD is the key-pair level for the grantor

    PagedList<Transaction, String> transactions = accounts.get(0)

        .getTransactionsBlocking(null, 10, STANDARD);

 

    // get the 10 most recent transactions in the specified start-end date range

    PagedList<Transaction, String> transactionsByDate = accounts.get(0)

        .getTransactionsBlocking(null, 10, STANDARD, "2019-01-15", "2022-01-15");

 

    // pass this offset to the next getTransactions

    // call to fetch the next page of transactions

    String nextOffset = transactions.getOffset();

 

    return transactions.getList();

}

Get Standing Orders

Accessing a customer's list of standing orders works in much the same way as one-time transactions. Here's the quick form:

public static List<StandingOrder> redeemStandingOrdersAccessToken(

    Member grantee,

    String tokenId) {

 

    // Specifies whether the request originated from a customer

    boolean customerInitiated = true;

 

    // access grantor's account list by applying

    // access token to the grantee client

    Representable grantor = grantee.forAccessToken(tokenId, customerInitiated);

    List<Account> accounts = grantor.getAccountsBlocking();

 

    // get the first 5 standing orders — here, STANDARD is the key-pair level

    //  for the grantor

    PagedList<StandingOrder, String> standingOrders = accounts.get(0)

        .getStandingOrdersBlocking(null, 5, STANDARD);

 

    // pass this offset to the next getStandingOrders

    // call to fetch the next page of standing orders

    String nextOffset = standingOrders.getOffset();

 

    return standingOrders.getList();

}

* * * *

Optionally, you can add a CustomerTrackingMetadata object to the redeemtypeAccessToken() method to supply customer tracking fields — customer-initiated (boolean), token-customer-ip-address, token-customer-device-id — for getBalances(), getTransactions(), and getStandingOrders() to let the bank know a particular API call was initiated by the PSUClosedPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both.. This may be useful in circumnavigating bank restrictions that impose a 4-times-a-day (i.e., within the same 24-hour period) access limit on the same AISPClosedAccount Information Service Provider – a TPP authorised to access consumer or business account data from the account holder's financial institutions with the account holder's explicit consent. in accordance with RTS regulationsClosedRegulatory Technical Standard – detailed specifications to achieve the strict security requirements for payment service providers in the EU..

For example:

.customer-initiated:true

.token-customer-ip-address:"127.0.0.1"

.token-customer-device-id:"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0:"

Using its tokenId, you can fetch any unredeemed (active), redeemed (endorsed), or canceled (cancelled) token at any time after the token is generated to review its parameters or to cancel the token altogether, as covered next.