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

Redeem a transfer token

Request

The POST /transfers endpoint is only required when you explicitly redeem the request token, i.e., auto-redeem is not enabled.

Security

Bearer or BasicAuth

Bodyapplication/jsonrequired

payloadobject(TransferPayloadRequest)required

Contains the financial details of the transfer.

payload.amountobject

payload.confirmFundsboolean(boolean)

Requests confirmation that sufficient funds are available.

Default false

Example: false

payload.descriptionstring

A description of the transfer.
Warning: If the 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.

payload.metadataobject(Metadata)

Information governing or otherwise related to the transfer instructions.

payload.refIdstring(refId)

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"

payload.tokenIdstringrequired

Identifies the authorization token for the transfer.

Example: "tt:8zK1dic95omjWb72gvc3z3ELKbTNfnGd89MbDnM73er4:ZhBVAJSH8DeU1"

payload.transferDestinationsArray of sepa (object) or sepaInstant (object) or fasterPayments (object) or elixir (object) or euDomesticNonEuro (object) or euDomesticNonEuroInstant (object) or bankgiro (object) or plusgiro (object) or token (object) or virtualAccount (object)(TransferDestinationRequest)

The beneficiary account specifying the transfer destination; i.e., TPP/merchant/creditor.

curl -i -X POST \
  https://api.token.io/transfers \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "amount": {
        "currency": "EUR",
        "value": "10.23"
      },
      "confirmFunds": false,
      "description": "string",
      "metadata": {
        "chargeBearer": "CRED",
        "providerTransferMetadata": {
          "cma9TransferMetadata": {
            "endToEndIdentification": "string",
            "instructionIdentification": "string",
            "risk": {
              "deliveryAddress": {
                "addressLine": [
                  "Flat 2, The Red Lodge, 1 High Street"
                ],
                "addressType": "BUSINESS",
                "buildingNumber": "1",
                "country": "GB",
                "countrySubDivision": [
                  "North Yorkshire"
                ],
                "department": "1",
                "postCode": "YO62 5JB",
                "streetName": "High Street",
                "subDepartment": "Flat 2",
                "townName": "York"
              },
              "merchantCustomerIdentification": "0000789123",
              "paymentContextCode": "PISP_PAYEE",
              "paymentPurposeCode": "DVPM",
              "beneficiaryAccountType": "BUSINESS",
              "contractPresentIndicator": "true",
              "beneficiaryPrepopulatedIndicator": "true"
            }
          }
        },
        "purposeCode": "DVPM",
        "ultimateCreditor": "ACME GmbH",
        "ultimateDebtor": "John Smith"
      },
      "refId": "9htio4a1sp2akdr1aa",
      "tokenId": "tt:8zK1dic95omjWb72gvc3z3ELKbTNfnGd89MbDnM73er4:ZhBVAJSH8DeU1",
      "transferDestinations": [
        {
          "customerData": {
            "address": {
              "city": "Berlin",
              "conscriptionNumber": "2831",
              "country": "DE",
              "district": "Friedrichshain",
              "flats": "21A - 21C",
              "full": "Fifth house on the left after the village oak, Smalltown, Smallcountry",
              "hamlet": "Botzowviertel",
              "houseName": "Grossen Blauen Haus",
              "houseNumber": "123",
              "place": "Arnswalder Platz",
              "postCode": "10243",
              "province": "BC",
              "state": "CA",
              "street": "Hans-Otto-Strasse",
              "subdistrict": "Friedrichshain Nord",
              "suburb": "Altona Meadows Suburb"
            },
            "legalNames": "Mr John Arthur Smith"
          },
          "type": "BUSINESS",
          "sepa": {
            "iban": "GB29NWBK60161331926819",
            "bic": "BOFIIE2D"
          }
        }
      ]
    }
  }'

Responses

Successful response

Bodyapplication/json

authorizationDetailsobject(ExternalAuthorizationDetails)

Contains the external authorization details provided by the bank.

transferobject(Transfer)

Information about each respective transfer record requested.

Response

application/json

{
  "authorizationDetails": {
    "authorizationUrl": "https://your-standing-order-credentials.com"
  },
  "transfer": {
    "actingAs": { … },
    "convertedToFutureDatedPayment": false,
    "createdAtMs": 1729212980771,
    "executionDate": "2023-01-28",
    "id": "tt:83KiRJuXmEDV5m2b8ZvLGE91ELf7PPw5BaDab98kMguu:3VMczyq7r7b6HwC",
    "payload": { … },
    "payloadSignatures": [ … ],
    "providerDetails": { … },
    "refund": { … },
    "refundDetails": { … },
    "source": { … },
    "status": "PROCESSING",
    "statusReasonInformation": "This transfer is processing.",
    "transactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV"
  }
}

Get transfers

Request

The GET /transfers endpoint retrieves information for all transfers.

Security

Bearer or BasicAuth

Query

tokenIdstring

Identifies the authorization token for the request.

Example: tokenId=rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq

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.tokenIdstring

Filters by the authorization token id.

Example: filter.tokenId=tt:3kFGtpEKHu8S2fJuEkb6YPnHZ4bJ2oUrYPCsJop68vCH:5zKcENpV

filter.startTimeMsstring(string)

Filtered list start time boundary in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000.

Example: filter.startTimeMs=72799

filter.endTimeMsstring(string)

Filtered list end time boundary in milliseconds, 1 day (24 hours) = 8640000000, 1 hour = 36000000, and 1 minute = 60000.

Example: filter.endTimeMs=3341983424

filter.transactionStatusstring(filter.transactionStatus)

Filters by transaction status.

PROCESSING – This status indicates that the transaction is in process and that the final status has not been received from the bank.
SUCCESS – This status indicates that successful payment initiation has been received from the bank. Settlement might not be complete.
INITIATED – This status is set when the previous status has remained as PROCESSING for 30 days and cannot be updated. The transaction has been initiated but the result is unknown. This is the final status and will not get updated later because Token.io has stopped polling the bank.
This status is also returned in a two-step payment flow in the event that a user’s request has been authorized at the bank but the payment confirmation has subsequently failed.
PENDING_EXTERNAL_AUTHORIZATION – This status indicates that the user has been sent to the bank to complete the authorization process. If not completed within the allowed timeframe (usually around 15 mins, but there are variations between banks) the transaction will expire and transition to FAILURE_EXPIRED. This status is only relevant for 1-step payment flows.
FAILURE_GENERIC – This status usually indicates a technical failure. Possibly, a failure callback was received from the bank, with no transaction status and no further information.
FAILURE_PERMISSION_DENIED – This status indicates that the user has been denied authorization at the bank This status is only relevant for two-step payment flows.
FAILURE_CANCELED – This status indicates that the payment initiation has been canceled before execution.
FAILURE_EXPIRED – This status indicates that the user did not complete the authorization process within the allowed timeframe (usually around 15 mins, but there are variations between banks) and the payment has expired.
FAILURE_INSUFFICIENT_FUNDS – This status indicates that the payment initiation request has been rejected due to insufficient funds.
FAILURE_DECLINED – This status indicates that the payment initiation has been rejected by the bank.
SETTLEMENT_IN_PROGRESS – This status is provided when a Token.io settlement account is used as the beneficiary for the payment, and replaces the payment initiation status. Token.io is waiting for the payment to reach the payee bank. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call. The status will change to SETTLEMENT_IN_PROGRESS soon after Token.io receives the final status from the debtor bank.
SETTLEMENT_COMPLETED – This status is provided when a Token.io settlement account is used as the beneficiary for the payment, and replaces the payment initiation status. The payment has reached the payee bank and Token.io has matched the transaction in the TPP’s settlement account to the initiated payment. For instant payments, SETTLEMENT_COMPLETED will be achieved within 30-45 minutes from payment initiation, at the latest. For non-instant payments, the time to reach SETTLEMENT_COMPLETED will depend on the clearing period for the payment.
SETTLEMENT_INCOMPLETE – This status is provided when a Token.io settlement account is used as the beneficiary for the payment, and replaces the payment initiation status. Reconciliation has failed. This happens when Token.io doesn't find the corresponding transaction in the TPP’s settlement account automatically.

During settlement of a settlement accounts payment, the status update job will run first for up to 30 days. Payment will then enter into a 'final' status, normally SUCCESS.
Once the status update job has run, the reconciliation job looks for matching inbound payments.For SEPA payments:

if a matching inbound payment is found within 15 days of the final payment status update -> SETTLEMENT_COMPLETED
if no matching inbound payment is found within 15 days of the final payment status update -> SETTLEMENT_INCOMPLETE

For SEPA Instant payments:

if a matching inbound payment is found within 1 day of the final payment status update -> SETTLEMENT_COMPLETED
if no matching inbound payment is found within 1 day of the final payment status update -> SETTLEMENT_INCOMPLETE

Enum"PROCESSING""SUCCESS""INITIATED""PENDING""PENDING_EXTERNAL_AUTHORIZATION""FAILURE GENERIC""FAILURE_PERMISSION_DENIED""FAILURE_CANCELED""FAILURE_EXPIRED""FAILURE_INSUFFICIENT_FUNDS"

Example: filter.transactionStatus=SUCCESS

filter.rolestring

Filters list by the account holder role.

Enum"ANY""PAYER""PAYEE"

Example: filter.role=PAYER

filter.actingAsRefIdstring

Filters the list by the sub-TPP identifier generated by Token.io once a TPP has been onboarded.

Example: filter.actingAsRefId=4kwl35c9sp3fwp4xq

filter.refIdstring

Filters list by refID.

Example: filter.refId=9htio4a1sp2akdr1aa

filter.transferRefundStatusstring

Filters list by refund status.

Enum"UNSET""NONE""PARTIAL""FULL"

Example: filter.transferRefundStatus=PARTIAL

curl -i -X GET \
  'https://api.token.io/transfers?tokenId=rq%3Aej5ACWNwi1EcqBeuDPc4Z8C4Bgc%3A5zKtXEAq&page.offset=LerV6Jmex&page.limit=175&filter.tokenId=tt%3A3kFGtpEKHu8S2fJuEkb6YPnHZ4bJ2oUrYPCsJop68vCH%3A5zKcENpV&filter.startTimeMs=72799&filter.endTimeMs=3341983424&filter.transactionStatus=SUCCESS&filter.role=PAYER&filter.actingAsRefId=4kwl35c9sp3fwp4xq&filter.refId=9htio4a1sp2akdr1aa&filter.transferRefundStatus=PARTIAL' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

offsetstring

The offset of the first item returned in the collection.

Example: "LerV6Jmex"

transfersArray of objects(Transfer)

Response

application/json

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

Get a transfer

Request

The GET /transfers/{transferId} endpoint retrieves information about a specific transfer in a given account.

Security

Bearer or BasicAuth

Path

transferIdstringrequired

The unique id of the transfer sent in the POST /transfers response and/or included in a respective GET /transfers response.

Query

skipTransferUpdateboolean(boolean)

If skipTransferUpdate is false, the request will call the bank for a status update. If set to true, the cached result will be returned instead.

Default false

Example: skipTransferUpdate=false

curl -i -X GET \
  'https://api.token.io/transfers/{transferId}?skipTransferUpdate=false' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

transferobject(Transfer)

Information about each respective transfer record requested.

Response

application/json

{
  "transfer": {
    "actingAs": { … },
    "convertedToFutureDatedPayment": false,
    "createdAtMs": 1729212980771,
    "executionDate": "2023-01-28",
    "id": "tt:83KiRJuXmEDV5m2b8ZvLGE91ELf7PPw5BaDab98kMguu:3VMczyq7r7b6HwC",
    "payload": { … },
    "payloadSignatures": [ … ],
    "providerDetails": { … },
    "refund": { … },
    "refundDetails": { … },
    "source": { … },
    "status": "PROCESSING",
    "statusReasonInformation": "This transfer is processing.",
    "transactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV"
  }
}

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

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

Redeem a transfer token

RequestExpand all

Responses

Get transfers

Request

Responses

Get a transfer

Request

Responses

Variable Recurring Payments

Refunds

Payouts

Settlement Accounts

Accounts

Tokens

Banks v1

Banks v2

Sub-TPPs

Authentication keys

Reports

Webhooks

Request