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

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

Create a sub-TPP

Request

The POST /member/sub-tpps endpoint creates a new sub-TPP for a reseller.

Security

Bearer or BasicAuth

Bodyapplication/jsonrequired

One of:

domainstringrequired

The fully qualified domain name of the sub-TPP, also referred to as the absolute domain name. This specifies an exact location in the tree hierarchy of the Domain Name System (DNS). It must include all domain levels, including the top-level domain and the root zone.

Example: "somehost.example.com"

logostring(byte)^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[...

This field specifies the image file containing the sub-TPP's logo as a byte array (click here for the JavaScript FileReader instance needed to convert the selected file into a byte array).

Example: "b0Y5cVl6aDc3RkE5blZyQ24yamlh"

merchantobject(member.Merchant)required

Contains information about the merchant member.

merchant.merchantJurisdictionstringrequired

The 'merchantJurisdiction' field specifies the jurisdiction in which the merchant operates. Previously, this field was referred to as the 'domicile country'.

Example: "DE"

merchant.legalEntityNamestringrequired

Full name of the merchant legal entity.

Example: "Test Merchant Entity Name"

merchant.companyRegistrationNumberstringrequired

Company registration number of merchant legal entity.

Example: "123456789"

merchant.primaryUseCasestringrequired

Merchant primary use case. Possible values include: AIS: Accounting package integration, AIS: Cash flow management, AIS: Credit risk analysis, AIS: Customer onboarding / verification, AIS: Personal finance management, PIS: eCommerce merchant payment, PIS: Funding an account, PIS: In store merchant payment, PIS: Paying a bill, PIS: Paying off debt

Example: "AIS: Accounting package integration"

merchant.ibanstringrequired

The IBAN of the bank where the payments are settled. The IBAN used will depend on the specific setup for each TPP/sub-TPP.
For example, this will be:

The sub-TPP's IBAN for cases where settlement is to the merchant.
The TPP's IBAN when the sub-TPP settles directly with the TPP.
A proxy for jurisdictions involved in the transaction.

Token.io checks the jurisdiction of the bank account and, where possible, confirms that the name on the account is valid; this name can be either the client's or the merchant's.
You must use a valid IBAN if you're testing in Sandbox.

Example: "DE0000000000000000000"

merchant.bicstring

BIC of merchant’s recipient bank account. You must use a valid IBAN if you're testing in sandbox.

Example: "BOFIIE2D"

namestringrequired

The recognised business name or DBA of the sub-TPP.

Example: "Sub-TPP Business Ltd"

parentSubTppIdstring(parentSubTppId)

The Token.io-generated identifier for the parent sub-TPP.

Example: "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s"

mccCodestring

Merchant Category Code is a four-digit number that classifies the type of goods or services a business offers.

useNewFlowboolean

When useNewFlow is set to true, the request is handled by the new merchant onboarding flow, rather than by the old flow.

Example: false

curl -i -X POST \
  https://api.token.io/member/sub-tpps \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "somehost.example.com",
    "logo": "b0Y5cVl6aDc3RkE5blZyQ24yamlh",
    "merchant": {
      "merchantJurisdiction": "DE",
      "legalEntityName": "Test Merchant Entity Name",
      "companyRegistrationNumber": "123456789",
      "primaryUseCase": "AIS: Accounting package integration",
      "iban": "DE0000000000000000000",
      "bic": "BOFIIE2D"
    },
    "name": "Sub-TPP Business Ltd",
    "parentSubTppId": "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s",
    "mccCode": "string",
    "useNewFlow": false
  }'

Responses

Successful response

Bodyapplication/json

subTppIdstring(subTppId)

The Token.io-generated identifier for the sub-TPP used by the reseller as the actingAs.refId in token requests.

Example: "8d54f066-c14a-47c0-b58b-fec6b0ed6b4c"

Response

application/json

{
  "subTppId": "8d54f066-c14a-47c0-b58b-fec6b0ed6b4c"
}

Get sub-TPPs

Request

The GET /member/sub-tpps endpoint retrieves a list of all sub-TPPs for a reseller.

Security

Bearer or BasicAuth

Query

page.offsetstring

The offset for the current page. If the offset has been provided in the request, this offset will be equal to the provided one. But if no offset was provided in the request (i.e. this is the first page) and the page is not empty, this field will be populated with a non-empty string. This may be helpful for loading the same page again, which might not always be possible with an empty offset due to a dynamic nature of the data.
The offset is not visible to a user and should not be parsed and/or understood in any way.

Example: page.offset=LerV6Jmex

page.limitinteger(int32)required

The maximum number of records to return. This must be less than 200.

Default 1

Example: page.limit=175

filter.byCompanyNamesArray of strings

Filters the sub-TPPs by the list of company names submitted.

Example: filter.byCompanyNames=["Company A","Company B","Company C"]

filter.byRegistrationDatesArray of strings

Filters the sub-TPPs by the list of registration dates submitted.

Example: filter.byRegistrationDates=["22-03-21","19-05-21","27-07-21"]

curl -i -X GET \
  'https://api.token.io/member/sub-tpps?page.offset=LerV6Jmex&page.limit=175&filter.byCompanyNames=%5B%22Company+A%22%2C%22Company+B%22%2C%22Company+C%22%5D&filter.byRegistrationDates=%5B%2222-03-21%22%2C%2219-05-21%22%2C%2227-07-21%22%5D' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

offsetstring

The offset of the first item returned in the collection.

Example: "LerV6Jmex"

subTppsArray of objects(member.SubTpp)

Contains each sub-TPP member onboarded by the reseller.

Response

application/json

{
  "offset": "LerV6Jmex",
  "subTpps": [
    { … }
  ]
}

Get sub-TPP information

Request

The GET /member/sub-tpps/{subTppId} endpoint retrieves the details of the specified sub-TPP for a reseller.

Security

Bearer or BasicAuth

Path

subTppIdstringrequired

This id specifies the sub-TPP to be retrieved.

Example: 8d54f066-c14a-47c0-b58b-fec6b0ed6b4c

curl -i -X GET \
  https://api.token.io/member/sub-tpps/8d54f066-c14a-47c0-b58b-fec6b0ed6b4c \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

subTppobject(member.SubTpp)

Contains the sub-TPP details.

Response

application/json

{
  "subTpp": {
    "childSubTppIds": [ … ],
    "createdAt": "2022-09-22T17:00:00.000Z",
    "domain": "somehost.example.com",
    "id": "8d54f066-c14a-47c0-b58b-fec6b0ed6b4c",
    "logo": "string",
    "memberId": "m:213xyzabc3453434",
    "merchant": { … },
    "name": "Sub-TPP Business Ltd",
    "parentSubTppId": "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s",
    "restrictedCountries": [ … ],
    "status": "ACTIVATED",
    "statusReasonInformation": "This sub-TPP has been activated.",
    "mccCode": "string",
    "updatedAt": "2022-09-22T17:00:00.000Z"
  }
}

Delete a sub-TPP

Request

The DELETE /member/sub-tpps/{subTppId} endpoint deletes an existing sub-TPP for a reseller.

Security

Bearer or BasicAuth

Path

subTppIdstringrequired

This id specifies the sub-TPP to delete.

Example: 8d54f066-c14a-47c0-b58b-fec6b0ed6b4c

curl -i -X DELETE \
  https://api.token.io/member/sub-tpps/8d54f066-c14a-47c0-b58b-fec6b0ed6b4c \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

object(DeleteSubTppResponse)

No data returned in the successful response.

Response

application/json

{}

Get sub-TPP children

Request

The GET /member/sub-tpps/{subTppId}/children endpoint retrieves the sub-TPP children for given sub-TPP.

Security

Bearer or BasicAuth

Path

subTppIdstringrequired

This id specifies the sub-TPP for which the children are to be retrieved.

Example: 8d54f066-c14a-47c0-b58b-fec6b0ed6b4c

curl -i -X GET \
  https://api.token.io/member/sub-tpps/8d54f066-c14a-47c0-b58b-fec6b0ed6b4c/children \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

subTppsArray of objects(member.SubTpp)

Response

application/json

{
  "subTpps": [
    { … }
  ]
}

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

Settlement Accounts

Accounts

Tokens

Banks v1

Banks v2

Sub-TPPs

Create a sub-TPP

RequestExpand all

Responses

Get sub-TPPs

Request

Responses

Get sub-TPP information

Request

Responses

Delete a sub-TPP

Request

Responses

Get sub-TPP children

Request

Responses

Authentication keys

Reports

Webhooks

Request