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

Initiate a refund

Request

The POST /refunds endpoint initiates a refund. After the refund is settled, the refund status of the original transfer will be updated.
The debtor field can be optional if you're using the debtor in registration. The creditor field can be optional if the information is available in the original payment.

Security

Bearer or BasicAuth

Bodyapplication/jsonrequired

initiationobject(RefundInitiation)required

The Initiation payload for the refund.

initiation.descriptionstring

The description of the refund.

Example: "refund for some reason"

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.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.originalPaymentIdstring(originalPaymentId)required

The original payment id from Token.io payments/transfers. This is required to initiate a refund. Token.io will check the original payment for the refund validation.

Example: "t:sdsds:sdsd"

initiation.registrationIdstring

The registration id.

Example: "regId"

initiation.localInstrumentstringrequired

The bank's payment service to be used for making a payment.

Enum"SEPA""SEPA_INSTANT""FASTER_PAYMENTS"

Example: "SEPA_INSTANT"

initiation.onBehalfOfIdstring

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

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

initiation.corporateApiDebtorobject(CorporateApiDebtorInformation)

The debtor information.

curl -i -X POST \
  https://api.token.io/refunds \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiation": {
      "description": "refund for some reason",
      "refId": "9htio4a1sp2akdr1aa",
      "amount": {
        "value": "10.23",
        "currency": "EUR"
      },
      "originalPaymentId": "t:sdsds:sdsd",
      "registrationId": "regId",
      "localInstrument": "SEPA_INSTANT",
      "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
      "corporateApiDebtor": {
        "accountId": "a12345"
      }
    }
  }'

Responses

Successful response

Bodyapplication/json

refundobject(Refund)

The refund object.

Response

application/json

{
  "refund": {
    "id": "rf:12345abcd:abcd",
    "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": "ACCP",
    "statusReasonInformation": "The payment is settled on debtor side.",
    "initiation": { … }
  }
}

Get refunds

Request

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

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 refund creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only refunds created at or after the given date will be returned.

Example: startDate=2010-01-01

endDatestring

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

Example: endDate=2010-01-01

idsArray of strings

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

Example: ids=rf:4QExXrhKTxfShBdcTeqFabqJJhUF:2gFUX1NDgpN&ids=rf:N5cJDFsQzVca3Qvr8kQocgEnjgX:2gFUX1NEdYA

invertIdsboolean

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

statusesArray of arrays

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

Example: statuses=INITIATION_COMPLETED&statuses=INITIATION_REJECTED

invertStatusesboolean

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

Example: invertStatuses=true

refIdsArray of strings

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

Example: refIds=ShBdcTeqFabqJJhUF&refIds=N5cJDFsQzVca3Q

partialboolean

Returns refunds in a partial format - with only id and status fields populated.

Example: partial=true

onBehalfOfIdsArray of strings

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

Example: onBehalfOfIds=c5a863bc-86f2-4418-a26f-25b24c7983c7&onBehalfOfIds=6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s

curl -i -X GET \
  'https://api.token.io/refunds?limit=10&offset=LerV6Jmex&startDate=2010-01-01&endDate=2010-01-01&ids=rf%3A4QExXrhKTxfShBdcTeqFabqJJhUF%3A2gFUX1NDgpN%2Crf%3AN5cJDFsQzVca3Qvr8kQocgEnjgX%3A2gFUX1NEdYA&invertIds=true&statuses=INITIATION_COMPLETED%2CINITIATION_REJECTED&invertStatuses=true&refIds=ShBdcTeqFabqJJhUF%2CN5cJDFsQzVca3Q&partial=true&onBehalfOfIds=c5a863bc-86f2-4418-a26f-25b24c7983c7%2C6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

refundsArray of objects(Refund)

pagingobject(PagingInfo)

Response

application/json

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

Get a refund

Request

The GET /refunds/{id} endpoint retrieves a given refund.

Security

Bearer or BasicAuth

Path

idstringrequired

The refund id.

Example: your refund id

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

Responses

Successful response

Bodyapplication/json

refundobject(Refund)

The refund object.

Response

application/json

{
  "refund": {
    "id": "rf:12345abcd:abcd",
    "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": "ACCP",
    "statusReasonInformation": "The payment is settled on debtor side.",
    "initiation": { … }
  }
}

Get all refunds by transfer

Request

The GET /transfers/{id}/refunds endpoint retrieves all refunds associated with a given transfer.

Security

Bearer or BasicAuth

Path

idstringrequired

The transfer id.

Example: your transfer id

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

curl -i -X GET \
  'https://api.token.io/transfers/your transfer id/refunds?limit=10&offset=LerV6Jmex' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

refundsArray of objects(Refund)

pagingobject(PagingInfo)

Response

application/json

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

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

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

Initiate a refund

RequestExpand all

Responses

Get refunds

Request

Responses

Get a refund

Request

Responses

Get all refunds by transfer

Request

Responses

Payouts

Settlement Accounts

Accounts

Tokens

Banks v1

Banks v2

Sub-TPPs

Authentication keys

Reports

Webhooks

Request