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

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

Initiate a payout

Request

The POST /payouts endpoint initiates a payout.

Security

Bearer or BasicAuth

Bodyapplication/jsonrequired

initiationobject(PayoutInitiation)required

The initiation payload for the payout.

initiation.descriptionstringrequired

The payment reference, which must consist of at least 6 alphanumeric characters that are not all the same. Optional, uncounted characters include space, hyphen(-), full stop (.), ampersand(&), and forward slash (/). The total of all characters must be no greater than 18 for SCAN (Sort Code and Account Number) payments and 140 for iban payments.

Example: "e49j-2145-sp17-k3h0"

initiation.refIdstring(refId)required

The TPP-generated reference identifier for the token. This is not to be confused with the requestId. The refId maps to the tppRefId in the bank's consentRequest. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the refId should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length.

Example: "9htio4a1sp2akdr1aa"

initiation.onBehalfOfIdstring

The OnBehalfOfId is validated against the sub-TPP id of the member before initiating the payout. This field is mandatory for unregulated TPPs.

Example: "c5a863bc-86f2-4418-a26f-25b24c7983c7"

initiation.amountobject(Amount)required

The transaction amount and currency.

initiation.amount.valuestringrequired

The transaction amount with up to four digits after the decimal point.

Example: "10.23"

initiation.amount.currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"

initiation.debtorCorporateApiDebtorInformation (object)required

CorporateApiDebtorInformation (object)

initiation.creditorobject(CreditorInformationPayout)required

The payout creditor object.

initiation.creditor.namestring

The owner's name for the creditor account.

Example: "Customer Inc."

initiation.creditor.ultimateCreditorNamestring

The ultimate creditor's name.

Example: "Customer Inc."

initiation.creditor.bankNamestring

The creditor's bank name.

initiation.creditor.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"

initiation.creditor.bicstring

The Business Identifier Code (BIC), ISO 9362, is the 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 can be either 8 or 11 characters long.

Example: "BOFIIE2D"

initiation.creditor.accountNumberstring

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

Example: "12345678"

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

curl -i -X POST \
  https://api.token.io/payouts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiation": {
      "description": "e49j-2145-sp17-k3h0",
      "refId": "9htio4a1sp2akdr1aa",
      "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
      "amount": {
        "value": "10.23",
        "currency": "EUR"
      },
      "debtor": {
        "accountId": "a12345"
      },
      "creditor": {
        "name": "Customer Inc.",
        "ultimateCreditorName": "Customer Inc.",
        "bankName": "string",
        "iban": "GB29NWBK60161331926819",
        "bic": "BOFIIE2D",
        "accountNumber": "12345678",
        "sortCode": 123456
      }
    }
  }'

Responses

Successful response

Bodyapplication/json

payoutobject(Payout)

The payout object.

Response

application/json

{
  "payout": {
    "id": "po:yj6sSEf7ZYFP8yxN6XWi1KkMEcB:2gFUX1NDget",
    "bankTransactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "memberId": "m:123456abcd:abcd",
    "createdDateTime": "2017-04-05T10:43:07.000+00:00",
    "updatedDateTime": "2017-04-05T10:45:07.000+00:00",
    "status": "INITIATION_COMPLETED",
    "bankPaymentStatus": "ACPC",
    "statusReasonInformation": "The payment is settled on debtor side.",
    "initiation": { … }
  }
}

Get payouts

Request

The GET /payouts endpoint retrieves a complete or filtered list of payouts.

Security

Bearer or BasicAuth

Query

limitinteger(int32)[ 1 .. 200 ]required

The maximum number of records to return.

Example: limit=10

offsetstring

The offset from the previous page.

Example: offset=LerV6Jmex

startDatestring

Lower bound for a payout creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only payouts created at or after the given date will be returned.

Example: startDate=2010-01-01

endDatestring

Upper bound for a payout creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only payouts created at or before the given date will be returned.

Example: endDate=2010-01-01

idsArray of strings

Filters payouts by their ids - returns only payouts with ids listed in this parameter.

Example: ids=po:28oivvd3iFhBrcbNj4tmtLEhxRTk:2gFUX1NE1T6&ids=po:3ZfdHxbpXmRZ1TVmiYNPgcwEocBy:2gFUX1NDdqr

invertIdsboolean

Invert ids query - returns only payouts with ids not listed in the ids parameter.

statusesArray of strings(PayoutStatus)

Filters payouts by their statuses - returns only payouts with statuses listed in this parameter.

Items Enum"INITIATION_PENDING""INITIATION_PROCESSING""INITIATION_COMPLETED""INITIATION_REJECTED""INITIATION_FAILED"

Example: statuses=INITIATION_COMPLETED&statuses=INITIATION_REJECTED

invertStatusesboolean

Invert statuses query - returns only payouts with statuses not listed in the statuses parameter.

Example: invertStatuses=true

refIdsArray of strings

Filters payouts by their refId values - returns only payouts with refIds listed in this parameter.

Example: refIds=ShBdcTeqFabqJJhUF&refIds=N5cJDFsQzVca3Q

onBehalfOfIdstring

Filters payouts by their onBehalfOfId value - returns only payouts 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/payouts?limit=10&offset=LerV6Jmex&startDate=2010-01-01&endDate=2010-01-01&ids=po%3A28oivvd3iFhBrcbNj4tmtLEhxRTk%3A2gFUX1NE1T6%2Cpo%3A3ZfdHxbpXmRZ1TVmiYNPgcwEocBy%3A2gFUX1NDdqr&invertIds=true&statuses=INITIATION_COMPLETED%2CINITIATION_REJECTED&invertStatuses=true&refIds=ShBdcTeqFabqJJhUF%2CN5cJDFsQzVca3Q&onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

payoutsArray of objects(Payout)

pagingobject(PagingInfo)

Response

application/json

{
  "payouts": [
    { … }
  ],
  "paging": {
    "limit": 0,
    "offset": "LerV6Jmex"
  }
}

Get a payout

Request

The GET /payouts/{id} endpoint retrieves a given payout.

Security

Bearer or BasicAuth

Path

idstringrequired

The payout id.

Example: your payout id

curl -i -X GET \
  'https://api.token.io/payouts/your payout id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

payoutobject(Payout)

The payout object.

Response

application/json

{
  "payout": {
    "id": "po:yj6sSEf7ZYFP8yxN6XWi1KkMEcB:2gFUX1NDget",
    "bankTransactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "memberId": "m:123456abcd:abcd",
    "createdDateTime": "2017-04-05T10:43:07.000+00:00",
    "updatedDateTime": "2017-04-05T10:45:07.000+00:00",
    "status": "INITIATION_COMPLETED",
    "bankPaymentStatus": "ACPC",
    "statusReasonInformation": "The payment is settled on debtor side.",
    "initiation": { … }
  }
}

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

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

Token.io's Open Banking API for TPPs

Payments v2

Requests - for Payments v1 or AIS

Transfers - for Payments v1

Variable Recurring Payments

Refunds

Payouts

Initiate a payout

RequestExpand all

Responses

Get payouts

Request

Responses

Get a payout

Request

Responses

Settlement Accounts

Accounts

Tokens

Banks v1

Banks v2

Sub-TPPs

Authentication keys

Reports

Webhooks

Request