Requesting Account Information (AIS)

PSD2ClosedPSD2 stands for Payment Services Directive 2 and is a new EU regulation in effect since September 14, 2019. It governs electronic and other non-cash payments. The main provision of PSD2 is for Strong Customer Authentication (SCA), a process that seeks to make online payments more secure and reduce fraud while increasing authorisation rates. The European Banking Authority (EBA) recently extended the deadline for PSD2 compliance until December 31, 2020. defines the "Account Information Service" as an online service to provide consolidated information (balance, transaction history) on one or more payment accounts held by a PSUClosedPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both. with one or more payment service providers.

As it relates to an 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., this essentially means that, under open banking protocols, banks allow access to a customer's account data by TPPs only if the customer (PSU) explicitly gives consent (grants permission) to let the bank allow such access.

In the context of the account information queries discussed here, AISP and TPPClosedThird-Party Provider – an authorised online service provider introduced as part of Open Banking. TPPs exist outside of the account holder’s relationship with their bank but may be involved in transactions carried out by the user. are one and the same.

The scope of analysis and service Token supports includes comparing a PSU's accounts and transaction history to a range of financial service options, aggregating data across participating financial institutions and customers to create marketing profiles, and making new transactions and account changes on the PSU's behalf.

To access Account Details, the value of supportsInformation must be true for each bank displayed to the user for selection from the GET /banks payload.

API support for accessing a PSU's account information institutes a communications flow that ensures all PSD2 mandates for PSU consent and authorisation are met.

Pictured above (hover to enlarge) is the general flow. Guidance on making the appropriate POST and GET calls, as well as handling Token's responses to these requests is covered next.

Correlated in the following table, the {{BASE_URL}} for calls and redirects depends on the environment in which you're operating.

Environment BASE_URL
API calls
Production https://api.token.io
Sandbox https://api.sandbox.token.io
Web App Redirect (for consent)
Production https://web-app.token.io
Sandbox https://web-app.sandbox.token.io

Be sure to include the BASE_URL for the appropriate environment and purpose in each call.

Typically, the bank requires a user ID as the first step of the credentials exchange necessary to identify the user. Additional details may be required, as well. These credentials and their format can be determined by calling GET /banks (see Filtering Banks by Desired Criteria). This will return a set of CredentialFields, specifying the credentials required initially; the set of credentials required in this first step are a statically-defined bank property.

Making a Token Request

To initiate a request with the bank for account information, you'll need to be able to identify yourself as a TPP in good standing using one of two ways; either your Member ID or your Alias, defined as follows:

  • Member ID – unique value generated by the Developer Dashboard when you signed up.
  • Alias – unique email or domain you supplied to the dashboard when you signed up.

For purposes of an AIS request — to avoid a mismatch caused by a typo — use both.

You can obtain the values from the dashboard by following these steps:

    (1)   If the dashboard isn't already open in a browser tab, sign in.

    (2)   Click Member Information in navigation panel on the left.

    (3)  Click the "eye" icon to the right of each value to reveal it.

    (4)   Copy the value you need.

Some banks in Germany, Austria and Hungary require the TPP to capture additional authentication information upfront from the user before a redirect to the bank.

If the selected bank imposes this initial credentials check requirement, you'll need to capture the credentialFields specified by the bank (e.g., the user's IBANClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself.) in its response to your GET /banks call (see Bank Selection using GET /banks) and include this information in your payment request.

In addition, when initial credentials are required by the user-selected bank, the redirect URL in the sandbox will be:

https://tpp-integration.sandbox.token.io/initiatePayment/callback?redirect-url={{your-redirect-url}}

For production, the redirect URL changes to:

https://tpp-integration.token.io/initiatePayment/callback?redirect-url={{your-redirect-url}}

Here, {{your-redirect-url}} is your standard TPP redirect URL.

The exchange iterations necessary to provide initial credential information to the bank take place in the background.

See also Mandatory Token Request Pass-ins and Authorisation Models in Bank Selection using GET /banks for information about providing required bank-specific information in your request. Please note that bank-specified MandatoryFields may be different for different banks.

If you are not connecting to a bank in Germany, Austria or Hungary, the requirement for an initial credentials check using the redirect URL format above does not apply and you should instead use the standard format outlined below.

Once the PSU gives consent for you to initiate AIS on the PSU's behalf, here's the call for POSTing /token-requests:

{

    "requestPayload": {

        "refId": "xyz",

        "to": {

            "alias": { // include only one type and its corresponding value

                "realmId": "value available from dashboard",

                "type": "EIDAS",

                "type": "EMAIL",

                "value": "noverify@token.io" // example value

                "value": "value available from dashboard"

            }

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"// TPP member ID

        },

        "authorizationMetadata": {   // map from response to GET /banks call

            "additionalProp1": "string",

            "additionalProp2": "string",

            "additionalProp3": "string"

        },

        "accessBody": {

            "type": [

                "ACCOUNTS",

                "BALANCES",

                "TRANSACTIONS"

                "TRANSFER_DESTINATIONS"

            ]

        },

        "description": "test",

        "redirectUrl": "https://sample-merchant-domain.com"

    }

}

The most important request fields and their corresponding descriptions are listed in the following table.

Key Fields in an Access Token Request
Field Description/Subfields Required/Optional
refId Reference identifier for the token; not to be confused with requestId.

RefId maps to tppRefId in the bank's consentRequest. It is needed to match/verify the originating token request with the bank's consent request.

Warning: A description mismatch between the originating token request and subsequent token lookups/changes/updates (retrieve, redeem, or cancel) will throw an exception.

Required
to Identifies the member initiating the request Required
alias A human-readable proxy for your member identifier that contains your realmId or alias type (DOMAIN, EMAIL, other) and a value string.

A realmId identifies a member created under the realm of a specific bank.

See Member Information in Understanding Dashboard Settings to find your member id and alias.

Required
id Member ID of the TPP, a constant value in all requests; see Member Information in Understanding Dashboard Settings. Required
authorizationMetadata Maps the key-value pairs from the GET /banksresponse, where key is the name of the field and value is the value of the field. Needed to capture additional information from the user for initial authorization by the bank, thereby allowing the user to proceed with providing consent for the initiation request. Required*
accessBody type Specifies the information for which access permission is requested:
  • ACCOUNTS – list of accounts with associated names
  • BALANCES – current balance of each requested account
  • TRANSACTIONS – recorded account activity in terms of debits and credits
  • TRANSFER_DESTINATIONS – account number and sort code, where applicable
Required
callbackState Developer-specified string allowing state to be persisted between the request and callback phases of the flow Optional
description Description of the payment with the following qualifiers:
  • description in a subsequent call must match description in originating request
  • description omitted in originating request must also be omitted in subsequent calls
  • description omitted in subsequent call will be replaced with refId

This description field maps to description in the bank's consentRequest presented to the user.

Warning: If description in a subsequent token request for lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception will be thrown.

Optional, with the caveats described in the previous column
redirectUrl Defines the bank's callback URL where your server initiates token redemption.

Important: When initial credentials are required by the bank as specified in its GET /banks response, see the note above for more on how to construct the redirect URL.

Required
token_expiration Sets the consent expiration in number of days for access requests (default is 90 days per PSD2ClosedPSD2 stands for Payment Services Directive 2 and is a new EU regulation in effect since September 14, 2019. It governs electronic and other non-cash payments. The main provision of PSD2 is for Strong Customer Authentication (SCA), a process that seeks to make online payments more secure and reduce fraud while increasing authorisation rates. The European Banking Authority (EBA) recently extended the deadline for PSD2 compliance until December 31, 2020. regulation); override of the default value is not supported by all banks. This is a particularly important parameter to pass to CMA9ClosedAs part of the Open Banking initiative, the CMA9 are the nine largest banks in the UK as determined by the Competition and Markets Authority (CMA). The CMA is an independent department of the UK government chartered to promote market competition and fairness, and reduce any harmful monopolies. banks to ensure an adequate custom consent expiry period is set for the access token upon successful authorisation.

JSON in a successful response payload will look something like this:

{"Data:["Permissions":["ReadAccountsDetails","ReadBalances"], "ExpirationsDateTime":"2020-10-21T18:03:07.371+01:00"}, "Risk":{}}

Optional
traceID TPP-provided unique value captured by Token and sent across to the bank to be stored with the request throughout its lifecycle as an audit-trail aid. Optional
*Inclusion of some elements may be optional or bank-dependent

Caution: A PANClosedPrimary Account Number – refers to a 14-, 15-, 16-, or even up to 19-digit number generated as a unique identifier designated for a primary account; also called payment card number and permanent card number. is disallowed in the token request payload within the refId and description fields. In accordance with the PA-DSSClosedPayment Application Data Security Standard – Council-managed program formerly under the supervision of the Visa Inc. program known as the Payment Application Best Practices (PABP). The goal of PA-DSS is to help software vendors and others develop secure payment applications that do not store prohibited data, such as full magnetic stripe, CVV2 or PIN data, and ensure their payment applications support compliance with the PCI DSS. Payment applications that are sold, distributed or licensed to third parties are subject to the PA-DSS requirements. In-house payment applications developed by merchants or service providers that are not sold to a third party are not subject to the PA-DSS requirements, but must still be secured in accordance with the PCI DSS. security standard, RegexClosedAPI to define a pattern for searching or manipulating strings. is used for pattern matching of numeric strings that intentionally or inadvertently reveal or resemble a PAN in the refId or description of a token request. Potential PAN patterns found will now throw an exception.

Here's an example of the response you'll receive:

{

   "tokenRequest": {

        "id": "rq:3RKfCA7KQEEZERLoFsAt3MoAnoP5:5zKtXEAq", // RequestId; add to BASE_URL for consent

        "requestPayload": {

            "redirectUrl": "https://sample-merchant-domain.com/ais"

            "to": {

                "alias": {

                    "type": "EMAIL",

                    "value": noverify@token.io"

                },

                "id": "m:23xPa7sYxTG2PeK72MmaFPT1RiPW:5zKtXEAq" // TPP member ID

            },

        "authorizationMetadata": {   // map from response to GET /banks call

            "additionalProp1": "string",

            "additionalProp2": "string",

            "additionalProp3": "string"

        },

            "accessBody": {

                "type": [

                    "ACCOUNTS",

                    "BALANCES",

                    "TRANSACTIONS",

                    "TRANSFER_DESTINATIONS"

                ]

            },

            "description": "test"

        }

    }

}

From the response, create the redirect URL by appending the request id (shown above in red) to the appropriate redirect BASE_URL, then send it to the user for the PSU's explicit consent.

https://{{BASE_URL}}/app/request-token/{{Insert request-id here}}

// example = https://web-app.sandbox.token.io/app/request-token/rq:3RKfCA7KQEEZERLoFsAt3MoAnoP5:5zKtXEAq

Tip: You can specify a particular language by passing its language code (lang=country-code) as a query parameter appended to the URL above, which the user can override in the webapp according to personal preference. Here's an example for passing the desired ISO 639-1ClosedCodes for the representation of names of languages—Part 1: Alpha-2 code, is the first part of the ISO 639 series of international standards for language codes. Part 1 covers the registration of two-letter codes. There are 184 two-letter codes registered as of December 2018. The registered codes cover the world's major languages. See https://www.iso.org/iso-639-language-codes.html language code for German (de):

https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?lang=de

After user consent is provided, the bank will redirect the user back to the TPP with tokenId as a query parameter.

"redirectUrl": "https://sample-merchant-domain.com"/ais?tokenId=sample_token_id

To derive the complete redirect URL, you'll need to URL decodeClosedURL encoding makes sure that the characters in the URL that are not allowed to be put into the URL directly can still be used. For example a space or : is not allowed, but replacing it with %20 or %3A encodes a space or : (and most browsers will display a space in the browser bar). For encoded URLs, use Java's URLDecoder (java.net.URLDecoder) unless you have a different preference. the tokenId value provided.

Using the tokenId sent by the bank, the TPP can now access everything for which the user gave consent. The scope of consent must correspond to the resources requested by the TPP in the POST /token requests call (within the accessbody.type array). All subsequent AIS guidance discussed here assumes that consent for the ACCOUNTS, BALANCES, TRANSACTIONS, and/or TRANSFER_DESTINATIONS is granted by the user.

Important: The GET /accounts calls discussed next must pass in an appropriate authorisation header. To review the details, see Construct the Request Authorisation Header for Token Authentication or Constructing the JWT Authorisation if you are using JWTClosedJSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the ayload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted..

GET /accounts

As a recognized TPP, access the user's account information by making a GET request to the /accounts endpoint. Remember to include the base URL.

Here's a simplified example of the bank's response:

{

    "accounts": [

        {

         "id": "a:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",

         "name": "N26 Main Checking",

         "bankId": "n26",

         "accountFeatures": {

             "supportsInformation": true,

             "supportsPayment": true,

         },

         "accountDetails": {

             "identifier": "MJzqR1A2NSgTg",

             "type": "CHECKING",

             "status": "ACTIVE",

             "metadata": {

                 "clientId": "1"

             }

         }

        },

        {

         "id": "a:6hLu9jSeDpXV9cWafdQxvxVFgoptZX65hwVWPgzCBBGL:5zKcENpV",

         "name": "N26 Savings",

         "bankId": "n26",

         "accountFeatures": {

             "supportsInformation": true,

             "supportsSendPayment": true,

             "supportsReceivePayment": true

         },

         "accountDetails": {

             "identifier": "r4KIihP9twv5",

             "type": "CHECKING",

             "status": "ACTIVE",

             "metadata": {

                 "clientId": "1"

             }

         }

    }

  ]

}

Key bank-dependent fields in the accounts object and their corresponding descriptions are listed in the following table.

Key Fields in the Bank's Account Access Response
Field Subfield Description
accountDetails accountHolderName Name of the individual listed as owner of the account
accountIdentifiers One of four supported categories of bank and account identification – bbanClosedBasic Bank Account Number – represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. See https://www.mobilefish.com/services/bban_iban/bban_iban.php for help with BBAN conversion., gbDomesticClosedDomestic bank account identifier in the United Kingdom. Contains accountNumber and sortCode. The ISO country code is assumed to be GB., ibanClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself., or tokenClosedOne of four supported categories of accountIdentifiers defined in the API's AccountDetails object. It identifies the user member's account by accountId and memberId.
bicClosedBank Identifier Code – a unique identifier for a specific financial institution. A BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code. String value representing the bank identification code
providerAccountDetails Specific information regarding the ASPSPClosedAccount Servicing Payment Services Provider – any financial institution that offers a payment account with online access. This includes banks and building societies. PSD2 requires ASPSPs to provide access to trusted third parties for initiating payments and accessing account information. required by the respective Open Banking API standard adopted by the bank:. These include additional ASPSP business identifiers and contact information (address, phone, email, etc.) for:

See the protobuf reference or Swagger spec (under the Model tab) for object and field details.

status Provider-dependent string (ex. "Active", "Inactive", etc.)
type Type of provider account; i.e., CHECKING, SAVINGS, LOAN, CARD, OTHER
accountFeatures requiresExternalAuth Boolean. PSUClosedPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both. must authenticate using an external (non-bank) mechanism/service
supportsInformation Boolean. Account information may be shared given upon verified customer consent
supportsPayment Boolean. Account supports authorised payment initiation
supportsSendPayment Boolean. Account can send payments
bankId System-generated Bank ID
id System-generated account ID
isLocked Boolean. The account is locked
name User-defined name of the account

Important Update: In the GET /accounts response payload, account_identifiers are now specified in accountDetails, which include bic and account_holder_name, along with account_number and/or sort_code. An example of the JSONClosedJavaScript Object Notation – a lightweight format for storing and transporting data, often when data is sent from a server to a web page. for account_identifiers might look something like this:

account_details {

    provider_aaccount_details {

        cma9_account_details {

            account_type: BUSINESS_ACCOUNT

            account_subtype: CURRENT_ACCOUNT}

    },

    account_identifiers: [

    {

       gb_domestic

          {sort_code: "700001",

           account_number: "70000005"}

    }

]}

Possible account_identifiers in the bank's response payload comprise:

Only fields supported by the responding bank will be populated.

Previously, TPPs could obtain these data — account identifiers, BICClosedBank Identifier Code – a unique identifier for a specific financial institution. A BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code., and customer name — after a GET /account call with a subsequent GET /account/{account_Id}/transfer-destinations call, wherein the debit-side bank returned its preferred transfer method(s) — SEPAClosedSingle Euro Payments Area – a payments system created by the European Union (EU) which harmonizes the way cashless payments transact between euro countries. European consumers, businesses, and government agents who make payments by direct debit, instant credit transfer, and through credit transfers use the SEPA architecture. The single euro payment area is approved and regulated by the European Commission. SEPA currently includes 36 members. It encompasses the 28 EU member states along with Iceland, Norway, Liechtenstein, Switzerland, Andorra, Vatican City, Monaco and San Marino. The single euro payment area remains an ongoing, collaborative process between these parties. SEPA is in the process of harmonizing rules regarding mobile and online payments., FPSClosedFaster Payments Service – UK banking initiative to reduce payment times between different banks' customer accounts from the three working days that transfers take using the long-established BACS system to typically a few seconds., DomesticClosedBanks make domestic wire transfers (as opposed to international wire transfers) to send funds to financial institutions residing in the same country or financial zone., etc. — along with the bic and CustomerData.

However, to optimise API utilisation and eliminate the additional call to transfer-destinations to get account details, banks are now required to populate account_identifiers, bic and account_holder_name in the accountDetails returned by the GET /accounts call.

GET /accounts/{account_id}/balance

To access the user's account balance information, the TPP can now make a GET request to the /accounts/{account_id}/balance endpoint, where {account_id} is an id (shown above in yellow) returned in the response.

Here's an example of the response to the GET /accounts{account-id}/balance call:

{

    "balance": {

        "accountId": "a:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",

        "current": {

            "currency": "USD",

            "value": "12009.1000"

        },

        "available": {

            "currency": "USD",

            "value": "12009.1000"

        }

    },

    "status": "SUCCESSFUL_REQUEST"

}

Key bank-dependent fields in the balance object and their corresponding descriptions are listed in the following table.

Key Fields in the Bank's Account Balance Response
Field Subfield Description
accountId System-generated account ID
available currency ISO currency code for the available balance
value Available balance valued in the designated currency; typical precision rounding to 4 decimal places (HALF-EVENClosedRound-half-even algorithm, often referred to as Banker's Rounding because it is commonly used in financial calculations. Half-way values are rounded toward the nearest even number. Thus, 3.5 will round up to 4 and 4.5 will round down to 4.), although this is entirely up to the bank. The Token Platform strictly serves as the pipeline between the TPP and the bank, imposing no precision restrictions.
current currency ISO currency code for the current balance
value Current balance valued in the designated currency.
otherBalances amount currency and value for other balances associated with the account, when applicable
type Bank-defined string indicating the type of balance

The status returned will be one of the following: INVALID_REQUEST, SUCCESSFUL_REQUEST, or MORE_SIGNATURES_NEEDED.

Note: The response status value MORE_SIGNATURES_NEEDED applies only to a scenario in which the bank requires the user to explicitly consent to a specific balance retrieval even though a valid access token exists. This is not a current requirement of any Token-connected bank and can therefore be disregarded until future notice.

An INVALID_REQUEST status in a response is the default setting that is always overridden when the API is invoked.

You can also retrieve balances for multiple accounts with a single call. Simply make the GET request to /account-balance?account_id={{ACCOUNT_ID_1}}&account_id={{ACCOUNT_ID_2}}&etc...

Tip: Use a GET /account-balance call to retrieve the associated balances for multiple accounts if the user holds more than one account at the bank. This call returns an array of accountIds, along with each respective account's balance, in contrast to the more targeted GET /accounts/{account-id}/balance call, which returns the balances (current and available) for the specified account only, as discussed above.

Based on the responses to these respective account balance queries, you can display the requested account information to the user.

GET /accounts/{account_id}/transactions

In accordance with the guidance above, a typical Transaction History payload for a selected account (based on a GET /accounts/{account_id}/transactions call takes the following form:

{

 "transactions": [{

     "id": "42909b155d4942299c39017686b5dc36",

      "type": "DEBIT",

      "status": "SUCCESS",

      "amount": {

          "currency": "EUR",

          "value": "100.0000"

      },

      "tokenId": "tt:3kFGtpEKHu8S2fJuEkb6YPnHZ4bJ2oUrYPCsJop68vCH:5zKcENpV",

      "tokenTransferId": "t:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",

      "createdAtMs": "1576788659686",

      "providerTransactionDetails": {}

 }],

 "offset": "pJUkL87QdDQu3mL9z1VK793RWasi19ERywLHP3L4uwjmEfcZPEPDU2R6rbDj6KbSogQcv",

 "status": "SUCCESSFUL_REQUEST"

}

Key bank-dependent fields in the transactions object and their corresponding descriptions are listed in the following table.

Key Fields in the Bank's Account Transactions Response
Field Subfield Description
amount currency ISO currency code for the transaction
value Amount of the transaction valued in currency
creditorEndpoint account Specific information about the creditor's account, including bank, account features, and payment method
accountIdentifier One of four supported categories of bank and account identification – bbanClosedBasic Bank Account Number – represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. See https://www.mobilefish.com/services/bban_iban/bban_iban.php for help with BBAN conversion., gbDomesticClosedDomestic bank account identifier in the United Kingdom. Contains accountNumber and sortCode. The ISO country code is assumed to be GB., ibanClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself., or tokenClosedOne of four supported categories of accountIdentifiers defined in the API's AccountDetails object. It identifies the user member's account by accountId and memberId.
bankId System-generated bank ID
customerData Address and legal name(s) related to the beneficiary account
description Description of the transaction
id Transaction ID
providerTransactionDetails Specific information regarding the transaction required by the respective Open Banking API standard adopted by the bank, such as the date-time of the transaction and pertinent instrument, business, and tax information, along with creditor and debtor identifiers for:

See the protobuf reference or Swagger spec (under the Model tab) for object and field details.

status PENDING, PROCESSING, SUCCESS, PENDING_EXTERNAL_AUTHORIZATION, FAILURE_CANCELED, FAILURE_INSUFFICIENT_FUNDS, FAILURE_INVALID_CURRENCY, FAILURE_PERMISSION_DENIED, FAILURE_QUOTE_EXPIRED, FAILURE_INVALID_AMOUNT, FAILURE_INVALID_QUOTE, FAILURE_EXPIRED, FAILURE_DECLINED, FAILURE_GENERIC, SENT, INITIATED, STATUS_NOT_AVAILABLE

See Payment Status: Values and Meaning for status definitions

tokenId System-generated transfer token ID
tokenTransferId System-generated Transfer ID for the transaction
type Transaction type — DEBIT or CREDIT

Certain banks do not encode the transaction id returned in their response; in which case, it falls to the TPP itself to encode the transaction id in order to retrieve an individual transaction record in a subsequent access request. Token does not manipulate or alter data returned by the bank.

For all calls, field values in the response are populated based on data returned by the bank. Field values that are not populated in a response were not provided by the bank.

Consistent with the request-response structure discussed above, the API also supports information access to standing order information (GET /accounts/{account_id}/standing-orders/{standing_order_id}), along with a specific account's established transfer destinations (GET /accounts/{account_id}/transfer-destinations) to fetch the IBANClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself..

Payee Information. Submission and return of payee information is not supported by all banks. When supported, and based on the standard adopted by the bank, creditor account (payee) information (legal name and/or address) is included in customerData within providerTransactionDetails for single transactions. When included in the request, payee information is available in the response, regardless of the API standard adopted by the bank; typically, however, the following guidelines apply:

Note: For all GET /account and GET /accounts endpoints, please ensure that you request permission for each desired endpoint — ACCOUNTS, BALANCES, TRANSACTIONS, and/or TRANSFER_DESTINATIONS — in the accessBody of your token request.

* * * *

Optionally, you can add a customer tracking header — customer-initiated (boolean), token-customer-ip-address, token-customer-device-id — to GET /accounts, GET /accounts/{account_id}/balance, and GET /accounts/{account_id}/transactions calls to let the bank know that 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., 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:

header 'customer-initiated:true'\

-header 'token-customer-ip-address:127.0.0.1'\

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

Please refer to the API's Swagger Reference for additional details on all of the above.