Single Immediate Payments v1

These endpoints allow you to submit new payment initiation requests and retrieve information about existing payments.

Redeem a transfer token

The POST /transfers endpoint creates a request to move money between accounts. This is only required for banks that support 2-step payments.

SecurityBearer or BasicAuth
Request
Request Body schema: application/json
required
required
object (TransferPayloadRequest)

Contains the financial details of the transfer.

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

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

post/transfers
Request samples
application/json
{
  • "payload": {
    }
}
Response samples
application/json
{
  • "authorizationDetails": {},
  • "transfer": {
    }
}

Get transfers

The GET /transfers endpoint retrieves information for all transfers.

SecurityBearer or BasicAuth
Request
query Parameters
tokenId
string

Identifies the authorization token for the request.

Example: tokenId=rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
page.offset
string

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.limit
required
integer <int32>
Default: 1

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

Example: page.limit=175
filter.tokenId
string

Filters by the authorization token id.

Example: filter.tokenId=tt:3kFGtpEKHu8S2fJuEkb6YPnHZ4bJ2oUrYPCsJop68vCH:5zKcENpV
filter.startTimeMs
string <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.endTimeMs
string <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.transactionStatus
string (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 after the user's request has been authorized at the bank and the POST /transfers call has been made to the bank in a 2-step flow, but the result is unknown because the call to the bank has timed out. (Previously, in this scenario the status SENT was returned).
  • 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 2-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 virtual 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 virtual 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 virtual 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 virtual 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" "FAILURE_DECLINED" "SETTLEMENT_IN_PROGRESS" "SETTLEMENT_COMPLETED" "SETTLEMENT_INCOMPLETE"
Example: filter.transactionStatus=SUCCESS
filter.role
string

Filters list by the account holder role.

Enum: "ANY" "PAYER" "PAYEE"
Example: filter.role=PAYER
filter.actingAsRefId
string

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

Example: filter.actingAsRefId=4kwl35c9sp3fwp4xq
filter.refId
string

Filters list by refID.

Example: filter.refId=9htio4a1sp2akdr1aa
filter.transferRefundStatus
string

Filters list by refund status.

Enum: "UNSET" "NONE" "PARTIAL" "FULL"
Example: filter.transferRefundStatus=PARTIAL
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

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

get/transfers
Request samples 
Response samples 
application/json
{
  • "offset": "LerV6Jmex",
  • "transfers": [
    ]
}
Initiate bank authorization
The POST /token-requests/{tokenRequestId}/authorization endpoint initiates the bank authorization process with a given bank id and token request id.


SecurityBearer or BasicAuth 
Request 
path Parameters
tokenRequestId
required
string
The token request id received in response to the original token request.


 
 Example:  rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
Request Body schema: application/json
required
consentAccepted
boolean <boolean> 
 Default:  false
This flag indicates whether the user has grated consent for the payment in the TPP's user interface.


 
 Example:  false
object (InitiateBankAuthorizationRequestCredentialsEntry) 
Maps a bank-defined credential id string to a value.


 
useCredentialFlow
boolean <boolean> 
 Default:  false
If true, this triggers the credential flow. The credentials map must be populated if required by the bank (see credentialFields in the response to GET /banks). Otherwise, empty credentials are used.


 
 Example:  false
useWebappCredentialsFlow
boolean <boolean> 
 Default:  false
When useWebAppCredentialsFlow is set to true and bank's flow includes embedded steps, these steps are handled by Token.io's Hosted Pages, rather than by the customer's own pages.


 
 Example:  false
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


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


post/token-requests/{tokenRequestId}/authorization
Request samples 
application/json
{
  • "consentAccepted": false,
  • "credentials": {
    },
  • "useCredentialFlow": false,
  • "useWebappCredentialsFlow": false
}
Response samples 
application/json
{
  • "fields": {
    },
  • "oauthState": "71b624cf-af3a-4f78-9420-d6e4248a9efe"
}
Get a transfer
The GET /transfers/{transferId} endpoint retrieves information about a specific transfer in a given account.


SecurityBearer or BasicAuth 
Request 
path Parameters
transferId
required
string
The unique id of the transfer sent in the POST /transfers response and/or included in a respective GET /transfers response.


 
query Parameters
skipTransferUpdate
boolean <boolean> 
 Default:  false
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.


 
 Example:  skipTransferUpdate=false
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


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/transfers/{transferId}
Request samples 
Response samples 
application/json
{
  • "transfer": {
    }
}
➔ Next to Variable Recurring Payments