Skip to content

Token.io's Open Banking API for TPPs

Token.io's Open Banking API

Token.io Support: support.token.io

The Token.io Open Banking API enables you to connect securely with banks for a range of services.

Using our API you can:

  • provide authorized access to an authenticated user's account information
  • get information on specific banks
  • initiate authorization with a user-selected bank
  • initate and track single immediate payments and future dated payments
  • use variable recurring payments (VRP) to grant long-held consents to Payment Initiation Service Providers (PISPs) to initiate series of payments from users' bank accounts
  • carry out settlements, payments and refunds using our settlement accounts

For more information see our developer documentation.

Download OpenAPI description
index.json
index.yaml
Languages
Servers

https://api.token.io/

Payments v2

These endpoints enable you to make v2 single immediate payments and future dated payments using the redirect, embedded and decoupled flows.

Operations

Requests - for Payments v1 or AIS

These endpoints allow you to initiate a Payments v1 request or an AIS request, and retrieve the status of the request.

Operations

Transfers - for Payments v1

These endpoints relate to transfers, which are requests to move money between accounts.

Operations

Variable Recurring Payments

These endpoints enable you to initiate Variable Recurring Payments (VRP).

Operations

Refunds

These endpoints allow you to handle registration, posting, and retrieval of refunds associated with original transaction account information.

Operations

Payouts

These endpoints allow you to make payouts.

Operations

Settlement Accounts

These endpoints provide authorized access to an authenticated user's settlement account information, enabling you to create settlement accounts, retrieve settlement account details, transactions and payouts, and manage settlement rules.

Operations

Create a settlement account

Request

The POST /virtual-accounts endpoint creates a settlement account.

Security
Bearer or BasicAuth
Bodyapplication/jsonrequired
accountNickNamestring

The alias name that identifies the settlement account. May contain up to 50 characters including letters, numbers, hyphens, underscores, and spaces.

Example: "Account Alias"
currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"
onBehalfOfIdstring

The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field will contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: "c5a863bc-86f2-4418-a26f-25b24c7983c7"
countrystring= 2 charactersrequired

Two-letter country code in upper case (ISO 3166-1 alpha-2).

Example: "GB"
curl -i -X POST \
  https://api.token.io/virtual-accounts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountNickName": "Account Alias",
    "currency": "EUR",
    "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
    "country": "GB"
  }'

Responses

Successful response

Bodyapplication/json
virtualAccountobject(VirtualAccount)
Response
application/json
{
  "virtualAccount": {
    "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
    "accountName": "Account Name",
    "accountNickName": "Account Alias",
    "accountNumber": "12345678",
    "availableBalance": 1572.38,
    "bic": "BOFIIE2D",
    "bookedBalance": 1282.79,
    "clearedBalance": 1167.32,
    "country": "GB",
    "createdDateTime": "2023-04-05T10:43:07.000+00:00",
    "currency": "EUR",
    "iban": "GB29NWBK60161331926819",
    "sortCode": 123456,
    "status": "ACTIVE",
    "updatedDateTime": "string",
    "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7"
  }
}

Get settlement accounts

Request

The GET /virtual-accounts endpoint retrieves information for all settlement accounts.

Security
Bearer or BasicAuth
Query
limitinteger(int32)

The maximum number of records to return.
The maximum allowed limit is 200. If the passed limit is bigger than this, it will be set to 200.

offsetstring

The offset for the current page. The offset is not required to fetch the first page. To fetch subsequent pages, use the 'nextOffset' value from the previous page response.
The offset value should not be parsed and/or understood in any way.

currencystring

The ISO 4217 three letter currency code.

Example: currency=EUR
countrystring

Two-letter country code in upper case (ISO 3166-1 alpha-2).

Example: country=PL
nicknamestring

The alias name that identifies the settlement account.

Example: nickname=Account Alias
onBehalfOfIdstring

The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
curl -i -X GET \
  'https://api.token.io/virtual-accounts?limit=0&offset=string&currency=EUR&country=PL&nickname=Account+Alias&onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
pageInfoobject(PageInfo)

The information about the current page, which also indicates whether the next page exists.

virtualAccountArray of objects(VirtualAccount)
Response
application/json
{
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  },
  "virtualAccount": [
    { … }
  ]
}

Get a settlement account

Request

The GET /virtual-accounts/{accountId} endpoint the information, for a given settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

Query
onBehalfOfIdstring

Filters payments by the onBehalfOfId value - returns only payments with the onBehalfOfId value specified in this parameter. This field is mandatory for unregulated TPPs.

Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
curl -i -X GET \
  'https://api.token.io/virtual-accounts/{accountId}?onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
virtualAccountobject(VirtualAccount)
Response
application/json
{
  "virtualAccount": {
    "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
    "accountName": "Account Name",
    "accountNickName": "Account Alias",
    "accountNumber": "12345678",
    "availableBalance": 1572.38,
    "bic": "BOFIIE2D",
    "bookedBalance": 1282.79,
    "clearedBalance": 1167.32,
    "country": "GB",
    "createdDateTime": "2023-04-05T10:43:07.000+00:00",
    "currency": "EUR",
    "iban": "GB29NWBK60161331926819",
    "sortCode": 123456,
    "status": "ACTIVE",
    "updatedDateTime": "string",
    "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7"
  }
}

Get settlement account transactions

Request

The GET /virtual-accounts/{accountId}/transactions endpoint retrieves transcation information in a given settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

Query
limitinteger(int32)

The maximum number of records to return.
The maximum allowed limit is 200. If the passed limit is bigger than this, it will be set to 200.

offsetstring

The offset for the current page. The offset is not required to fetch the first page. To fetch subsequent pages, use the 'nextOffset' value from the previous page response.
The offset value should not be parsed and/or understood in any way.

refIdstring

Filters transactions by their refId value - returns only transactions with refId mentioned in the reference.

startDatestring

Returns transactions created on or after this date, inclusive (in ISO 8601 format).

Example: startDate=2022-04-05
endDatestring

Returns transactions created on or before this date, inclusive (in ISO 8601 format).

Example: endDate=2022-04-05
amountstring

Filters transactions by their transaction amount.

providerPaymentIdstring

Filters transactions by the provider-payment-id.

transactionTypestring(TransactionType)

Filters transactions by type to include only CREDIT or DEBIT transactions.

Default "INVALID_TYPE"
Enum"INVALID_TYPE""DEBIT""CREDIT"
Example: transactionType=CREDIT
onBehalfOfIdstring

Filters payments by the onBehalfOfId value - returns only payments with onBehalfOfId specified in this parameter. This field is mandatory for unregulated TPPs.

Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
curl -i -X GET \
  'https://api.token.io/virtual-accounts/{accountId}/transactions?limit=0&offset=string&refId=string&startDate=2022-04-05&endDate=2022-04-05&amount=string&providerPaymentId=string&transactionType=CREDIT&onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
pageInfoobject(PageInfo)

The information about the current page, which also indicates whether the next page exists.

transactionsArray of objects(VirtualAccountTransactions)
Response
application/json
{
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  },
  "transactions": [
    { … }
  ]
}

Get a settlement account transaction

Request

The GET /virtual-accounts/{accountId}/transactions/{providerPaymentId} endpoint retrieves information for a specific transaction in a given settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

providerPaymentIdstringrequired

The settlement account provider-assigned unique transaction identifier.

Query
onBehalfOfIdstring

Filters payments by the onBehalfOfId value - returns only payments with onBehalfOfId specified in this parameter. This field is mandatory for unregulated TPPs.

Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
curl -i -X GET \
  'https://api.token.io/virtual-accounts/{accountId}/transactions/{providerPaymentId}?onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
transactionobject(VirtualAccountTransaction)

Information about the requested transaction.

Response
application/json
{
  "transaction": {
    "amount": { … },
    "providerPaymentId": "83KiRJuXm",
    "createdDateTime": "2017-04-05T10:43:07.000+00:00",
    "description": "Payment",
    "transactionType": "INVALID_TYPE",
    "localInstrument": "SEPA_INSTANT",
    "debtor": { … },
    "creditor": { … },
    "refId": "9htio4a1sp2akdr1aa",
    "transferId": "t:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "paymentId": "pm2:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "refundId": "rf:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "payoutId": "po:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV"
  }
}

Create a settlement rule

Request

The POST /virtual-accounts/{accountId}/settlement-rule endpoint creates a settlement rule, for a given settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

Bodyapplication/jsonrequired
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

Example: "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
payeeAccountDetailsobject(Creditor)required
payeeAccountDetails.​namestring

The owner name for the creditor account.

Example: "Customer Inc."
payeeAccountDetails.​ultimateCreditorNamestring

The ultimate creditor name.

Example: "Customer Inc."
payeeAccountDetails.​bankNamestring

The creditor's bank name.

payeeAccountDetails.​accountNumberstring

The unique identifier for the bank account in the UK or Ireland.

Example: "12345678"
payeeAccountDetails.​bicstring

The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long."

Example: "HBUKGB7F261"
payeeAccountDetails.​ibanstring

The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters.

Example: "GB29NWBK60161331926819"
payeeAccountDetails.​sortCodestring

The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland.

Example: 123456
amountTypestring(AmountType)required

The type of the amount.

Enum"FIXED_VALUE""PERCENTAGE"
amountValuestringrequired

The value of the amount.

Example: 10
timeIntervalstring(TimeInterval)required

The time interval.

Enum"INTRADAY""DAILY""WEEKLY""MONTHLY""QUARTERLY""HALF_YEARLY""YEARLY"
effectiveFromstring

The start date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.

Example: "2024-01-01T12:34:56Z"
effectiveTostring

The end date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.

Example: "2024-12-01T12:34:56Z"
intradayIntervalHoursinteger(int32)required

The intraday interval hours.

Example: 2
intradayIntervalMinutesinteger(int32)

The intraday interval minutes.

Example: 10
curl -i -X POST \
  'https://api.token.io/virtual-accounts/{accountId}/settlement-rule' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
    "payeeAccountDetails": {
      "name": "Customer Inc.",
      "ultimateCreditorName": "Customer Inc.",
      "bankName": "string",
      "accountNumber": "12345678",
      "bic": "HBUKGB7F261",
      "iban": "GB29NWBK60161331926819",
      "sortCode": 123456
    },
    "amountType": "FIXED_VALUE",
    "amountValue": 10,
    "timeInterval": "INTRADAY",
    "effectiveFrom": "2024-01-01T12:34:56Z",
    "effectiveTo": "2024-12-01T12:34:56Z",
    "intradayIntervalHours": 2,
    "intradayIntervalMinutes": 10
  }'

Responses

Successful response

Bodyapplication/json
settlementRuleIdstring(uuid)

The id of the settlement rule.

Example: "123e4567-e89b-12d3-a456-426614174000"
Response
application/json
{
  "settlementRuleId": "123e4567-e89b-12d3-a456-426614174000"
}

Get settlement rules

Request

The GET /virtual-accounts/{accountId}/settlement-rules endpoint retrieves information about settlement rules, for a given settlement account, according to the settlement rule status in the request. If no status is provided, the endpoint retrieves all settlement rules for the settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

Bodyapplication/jsonrequired
accountIdstring

The settlement account id.

Example: "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
statusstring(SettlementRuleStatus)

The status of the settlement rule.

Enum"ACTIVE""INACTIVE"
curl -i -X GET \
  'https://api.token.io/virtual-accounts/{accountId}/settlement-rules' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
    "status": "ACTIVE"
  }'

Responses

Successful response

Bodyapplication/json
settlementRuleArray of objects(SettlementRule)
Response
application/json
{
  "settlementRule": [
    { … }
  ]
}

Get a settlement rule

Request

The GET /virtual-accounts/{accountId}/settlement-rules/{settlementRuleId} endpoint retrieves information for a specific settlement rule, for a given settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

settlementRuleIdstringrequired

The id of the settlement rule.

curl -i -X GET \
  'https://api.token.io/virtual-accounts/{accountId}/settlement-rules/{settlementRuleId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
settlementRuleobject(SettlementRule)
Response
application/json
{
  "settlementRule": {
    "settlementRuleId": "c65e5548-682b-4c4e-b000-f496e06d1082",
    "payerAccountId": "string",
    "payeeAccountDetails": { … },
    "amountType": "FIXED_VALUE",
    "amountValue": "string",
    "effectiveFrom": "string",
    "effectiveTo": "string",
    "timeInterval": "INTRADAY",
    "status": "ACTIVE"
  }
}

Delete a settlement rule

Request

The DELETE /virtual-accounts/{accountId}/settlement-rules/{settlementRuleId} endpoint delete an active settlement rule, for a given settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

settlementRuleIdstringrequired

The id of the settlement rule.

curl -i -X DELETE \
  'https://api.token.io/virtual-accounts/{accountId}/settlement-rules/{settlementRuleId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
object(DeleteVirtualAccountSettlementRuleResponse)

No data returned in the successful response.

Response
application/json
{}

Get settlement account payouts

Request

The GET /virtual-accounts/{accountId}/settlement-rule-payouts endpoint retrieves information about payouts created by a settlement rule, for a given settlement account.

Security
Bearer or BasicAuth
Path
accountIdstringrequired

The system-generated, unique id which specifies the settlement account.

Bodyapplication/jsonrequired
accountIdstring

The settlement account id.

Example: "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
limitinteger(int32)

The maximum number of items to return in the response.

Example: 10
offsetstring

The offset of the first item to return in the response.

Example: "LerV6Jmex"
settlementRuleIdstring

The id of the settlement rule.

Example: "123e4567-e89b-12d3-a456-426614174000"
startDatestring

The start date of the settlement rule payout.

Example: "2024-01-01"
endDatestring

The end date of the settlement rule payout.

Example: "2024-12-01"
idsArray of strings

The list of payout ids.

Example: ["123e4567-e89b-12d3-a456-426614174000"]
invertIdsboolean

If true, the response will contain all settlement rule payouts except those specified in the ids field.

Example: false
statusesArray of strings

The list of payout statuses.

Example: ["INITIATION_PENDING","INITIATION_PROCESSING"]
invertStatusesboolean

If true, the response will contain all settlement rule payouts except those specified in the statuses field.

Example: false
refIdsArray of strings

The list of settlement payout reference ids.

Example: ["ShBdcTeqFabqJJhUF"]
curl -i -X GET \
  'https://api.token.io/virtual-accounts/{accountId}/settlement-rule-payouts' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
    "limit": 10,
    "offset": "LerV6Jmex",
    "settlementRuleId": "123e4567-e89b-12d3-a456-426614174000",
    "startDate": "2024-01-01",
    "endDate": "2024-12-01",
    "ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "invertIds": false,
    "statuses": [
      "INITIATION_PENDING",
      "INITIATION_PROCESSING"
    ],
    "invertStatuses": false,
    "refIds": [
      "ShBdcTeqFabqJJhUF"
    ]
  }'

Responses

Successful response

Bodyapplication/json
pageInfoobject(PageInfo)

The information about the current page, which also indicates whether the next page exists.

payoutsArray of objects(SettlementRulePayout)
Response
application/json
{
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  },
  "payouts": [
    { … }
  ]
}

Accounts

These endpoints provide authorized access to an authenticated user's account information.

Operations

Tokens

These endpoints retrieve all tokens, a filtered list of tokens, or a specific token, as well as allowing you to cancel an existing token.

Operations

Banks v1

These endpoints filter and fetch the list of connected banks, get information on specific banks, and initiate authorization with user-selected banks using Payments v1.

Operations

Banks v2

This endpoint filters and fetches the list of connected banks, gets information on specific banks, and initiates authorization with user-selected banks using Payments v2.

Operations

Sub-TPPs

These endpoints are for resellers using Token.io's licence to create, retrieve and delete sub-TPPs.

Operations

Authentication keys

These endpoints are for managing the public keys that are used for JWT authentication.

Operations

Reports

These endpoints retrieve the current AIS and PIS status of connected banks.

Operations

Webhooks

These endpoints configure, retrieve and remove webhooks. See Webhooks for more details.

Operations