Token.io's Open Banking API for TPPs (v1.2.3.8)

Download OpenAPI specification:Download

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 virtual accounts

For more information see our developer documentation.

Single Immediate Payments v2

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

Initiate a payment

The POST /v2/payments endpoint enables you to initiate a payment with a bank.

Once the payment has been initiated, the end user needs to authenticate themselves with their bank.

Check payment status:

  1. If the status in the initiation response is INITIATION_PENDING_REDIRECT_AUTH, redirect the user to the redirect url found in the authentication payload of the payment, to authenticate at the bank.

  2. If the status in the initiation response is INITIATION_PENDING_EMBEDDED_AUTH, collect the requested data listed in the authentication payload of the payment and use the POST /v2/payments/{paymentId}/embedded-auth endpoint to provide the requested field values.

  3. If the status in the initiation response is INITIATION_PENDING, Token.io needs more time to process this request with the bank. In the case of a successful scenario, the status will be updated to INITIATION_PENDING_REDIRECT_AUTH, INITIATION_PENDING_EMBEDDED_AUTH or INITIATION_PENDING_DECOUPLED_AUTH when the authentication details are ready. The update can be checked by the GET /v2/payments/{paymentId} endpoint or received via a webhook (see Webhooks).

  4. If the status is INITIATION_PENDING_DECOUPLED_AUTH, the bank has requested a decoupled authentication from the user and Token.io is awaiting the result. No further action is required.

  5. If the status is PENDING_MORE_INFO and you're not using Token.io's Hosted Payment Page (HPP), you need to populate the required information and make the payment initiation call again. Information about the missing data can be found in the statusReasonInformation field. If you're using Token.io's Hosted Payment Page, the required data will be collected from the user. You'll need to redirect the user to Token.io's Hosted Payment Page url constructed with the returned payment id.

request-timeout header:

Banks may take some time to respond when an initial request is made for an authorisation url. Therefore, Token.io recommends that you set a request-timeout header in your API-only POST /v2/payments requests. If this is set, Token.io sends a response when this timeout period has passed and will send a follow up response as soon as the bank has responded.
The following example demonstrates what happens when you set a timeout of 10 seconds and the call to the bank takes 15 seconds:

  1. The TPP makes a POST /v2/payments call.

  2. Tolen.io creates a resource with the status INITIATION_PENDING.

  3. Token.io starts the call to the bank.

  4. After 10 seconds from (1): Token.io returns the payment status INITIATION_PENDING.

  5. After 15 seconds from (3): Token.io receives a response from the bank and changes the status to, for example, INITIATION_PENDING_REDIRECT_AUTH.

  6. The TPP makes the GET /v2/payments/{id} call and receives the payment with the status INITIATION_PENDING_REDIRECT_AUTH.

SecurityBasicAuth or Bearer
Request
header Parameters
request-timeout
integer

Sets the number of elapsed seconds until the call is aborted with a DEADLINE_EXCEEDED exception due to no response received.

Example: 10
Request Body schema: application/json
required
required
object (PaymentInitiation)

The initiation payload for the payment.

pispConsentAccepted
boolean
Default: false

This field confirms whether or not the user has accepted Payment Initiation Service Provider (PISP) consent. This field is only required for TPPs using Token.io's licence.

initialEmbeddedAuth
object

This field provides a map of the initial embedded authentication fields, with their values. The list of the required initial credentials can be found in the bank metadata. Please use the id of each field as a key in the map.

Using this field is optional. Even if a bank requires initial embedded authentication fields, you may choose not to populate the initialEmbeddedAuth field. In this case you'll be able to provide these fields later in the flow as part of an embedded authentication step.

Responses
200

Successful response

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

500

An unexpected or internal server error

post/v2/payments
Request samples
application/json
{
  • "initiation": {
    },
  • "pispConsentAccepted": false,
  • "initialEmbeddedAuth": {
    }
}
Response samples
application/json
{
  • "payment": {
    }
}

Get payments

The GET /v2/payments endpoint provides you with a list of payments and their details.

SecurityBasicAuth or Bearer
Request
query Parameters
limit
required
integer <int32> [ 1 .. 200 ]

The maximum number of records to return.

Example: limit=10
offset
string

The offset from the previous page.

Example: offset=LerV6Jmex
ids
Array of strings

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

Example: ids=pm2:4QExXrhKTxfShBdcTeqFabqJJhUF:2gFUX1NDgpN&ids=pm2:N5cJDFsQzVca3Qvr8kQocgEnjgX:2gFUX1NEdYA
invertIds
boolean

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

statuses
Array of strings (PaymentStatus)

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

Items Enum: "INITIATION_PENDING" "INITIATION_PENDING_MORE_INFO" "INITIATION_PENDING_REDIRECT_AUTH" "INITIATION_PENDING_REDIRECT_AUTH_VERIFICATION" "INITIATION_PENDING_EMBEDDED_AUTH" "INITIATION_PENDING_EMBEDDED_AUTH_VERIFICATION" "INITIATION_PENDING_DECOUPLED_AUTH" "INITIATION_PENDING_REDEMPTION" "INITIATION_PENDING_REDEMPTION_VERIFICATION" "INITIATION_PROCESSING" "INITIATION_COMPLETED" "INITIATION_REJECTED" "INITIATION_REJECTED_INSUFFICIENT_FUNDS" "INITIATION_FAILED" "INITIATION_DECLINED" "CANCELED" "INITIATION_NO_FINAL_STATUS_AVAILABLE" "SETTLEMENT_IN_PROGRESS" "SETTLEMENT_COMPLETED" "SETTLEMENT_INCOMPLETE"
Example: statuses=INITIATION_COMPLETED&statuses=INITIATION_REJECTED
invertStatuses
boolean

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

Example: invertStatuses=true
createdAfter
string

Returns only payments created after this time (in ISO 8601 format).

Example: createdAfter=2022-04-05T17:00:00.000Z
createdBefore
string

Returns only payments created before this time (in ISO 8601 format).

Example: createdBefore=2022-04-05T17:00:00.000Z
refIds
Array of strings

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

Example: refIds=ShBdcTeqFabqJJhUF&refIds=N5cJDFsQzVca3Q
onBehalfOfId
string

Filters payments by the onBehalfOfId value - returns only payments with onBehalfOfId specified in this parameter.

Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
refundStatuses
Array of strings (PaymentRefundStatus)

Filters payments by their refund status values - returns only payments with refund statuses listed in this parameter.

Items Enum: "NONE" "PARTIAL" "FULL"
Example: refundStatuses=PARTIAL&refundStatuses=NONE
partial
boolean

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

Example: partial=true
Responses
200

Successful response

400

The client specified an invalid argument.

401

The authorization information is missing or invalid

500

An unexpected or internal server error

get/v2/payments
Request samples 
Response samples 
application/json
{
  • "payments": [
    ],
  • "pageInfo": {
    }
}
Provide information for embedded authentication
The POST /v2/payments/{paymentId}/embedded-auth endpoint provides you with the requested information when the payment status is INITIATION_PENDING_EMBEDDED_AUTH. The requested information can be found in the authentication field of the payment. 
 
 It's possible that some banks might request the user's input multiple times. In this case you might need to call this endpoint again for a new field set.


SecurityBasicAuth or Bearer 
Request 
path Parameters
paymentId
required
string
 
Request Body schema: application/json
required
embeddedAuth
object (EmbeddedAuthFields) 
This field provides a map of all fields requested for embedded authentication, with their values. The key is the id of the field from the authentication payload, for which this value is submitted.


 
Responses 
200
Successful response


400
The client specified an invalid argument.


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a payment, was not found


500
An unexpected or internal server error


post/v2/payments/{paymentId}/embedded-auth
Request samples 
application/json
{
  • "embeddedAuth": {
    }
}
Response samples 
application/json
{
  • "payment": {
    }
}
Get a payment
The GET /v2/payments/{paymentId} endpoint provides you with details of an individual payment and checks the payment status for the next step, if any.


SecurityBasicAuth or Bearer 
Request 
path Parameters
paymentId
required
string
 
Responses 
200
Successful response


401
The authorization information is missing or invalid


404
The requested entity, such as a payment, was not found


500
An unexpected or internal server error


get/v2/payments/{paymentId}
Request samples 
Response samples 
application/json
{
  • "payment": {
    }
}
➔ Next to Single Immediate Payments v2