Payments v2

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

Operations

Initiate a payment

Request

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:

If the status in the initiation response is INITIATION_PENDING_REDIRECT_AUTH or INITIATION_PENDING_REDIRECT_HP, redirect the user to the redirect url found in the authentication payload of the payment, to authenticate at the bank or at Token.io's Hosted Pages.

If the status in the initiation response is INITIATION_PENDING_REDIRECT_PBL, redirect the user to the payment link (redirect URL) found in the authentication payload. The user will be taken to Token.io’s Hosted Pages, where any missing information (such as amount or reference) can be provided before proceeding with payment authentication.

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.

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

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.

request-timeout header:

Banks may take some time to respond when a request is made. Therefore, Token.io recommends that you set a request-timeout header in your API-only POST /v2/payments requests to match the timeout of your client and avoid DEADLINE_EXCEEDED errors. If this is set, Token.io sends a response when this timeout period has passed and will update payment status 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:

The TPP makes a POST /v2/payments call.

Token.io creates a resource with the status INITIATION_PENDING.

Token.io starts the call to the bank.

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

After 15 seconds from (3): Token.io receives a response from the bank and changes the status to, for example, INITIATION_PENDING_REDIRECT_AUTH. The update will be sent in a webhook, if TPP is subscribed for webhooks.

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

Security

Bearer or BasicAuth

Headers

request-timeoutinteger

Sets the number of elapsed seconds until Token.io sends the response back, even if the call is not finished by that time (in which case the call will be completed asynchronously).

Example: 10

Bodyapplication/jsonrequired

initiationPay By Link Flow Type (object) or Other Flow Types (object)(PaymentInitiation)required

One of:

The initiation payload for the payment. If the Flow Type is PAY_BY_LINK_HOSTED_PAGES — amount and remittanceInformationPrimary are optional

initiation.bankIdstring(bankId)

The Token.io id of the bank where the consent is created. This field is required if the customer is not using Token.io's Hosted Pages for bank selection, i.e., API-only integration when EMBEDDED_HOSTED_PAGES is selected in flowType, or Hosted Pages embedded (modal) integration.

Example: "ob-modelo"

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.remittanceInformationPrimarystring(remittanceInformationPrimary)

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

initiation.onBehalfOfIdstring

The id of the ultimate client on whose behalf the consent is created. If the consent is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

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

initiation.amountobject(Amount)

The transaction amount and currency.

initiation.localInstrumentstring(localInstrument)required

The bank's payment service used to make the payment.
Depending on which local instrument you select, you will require different account identifiers in the debtor and creditor objects. The creditor object is mandatory, but the debtor object is only required if it is mandatory for a specific bank. However, if the TPP decides to provide debtor details, account identifier field(s) within the debtor object are mandatory.
The fields within the creditor and debtor objects are populated as follows:

FASTER_PAYMENTS require the sortCode and accountNumber to be populated.
SEPA and SEPA_INSTANT require the iban, the bic is optional.
ELIXIR requires either the iban or the Polish domestic accountNumber, the bic is optional.
BANKGIRO requires the bankgiroNumber, the bic is optional.
PLUSGIRO requires the plusgiroNumber, the bic is optional.
EU_DOMESTIC_NON_EURO and EU_DOMESTIC_NON_EURO_INSTANT require either the iban or bban, the bic is optional, OR the bban is required and clearingNumber is optional. For an HP flow that doesn't have a preselected bankId, a SENoBankId account, where the currency is SEK or NOK, will require an iban and bban with an optional bic and/or clearingNumber.

Enum"SEPA""SEPA_INSTANT""FASTER_PAYMENTS""ELIXIR""EU_DOMESTIC_NON_EURO""EU_DOMESTIC_NON_EURO_INSTANT""BANKGIRO""PLUSGIRO"

Example: "SEPA"

initiation.debtorSepaAccount (object) or SepaInstantAccount (object) or FasterPaymentsAccount (object) or ElixirAccount (PLIbanAccount (object)) or (EUDomesticNonEuroAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object))) or (EUDomesticNonEuroInstantAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object))) or BankGiroAccount (object) or PlusGiroAccount (object)(DebtorInformation)

One of:

The debtor information. The account identifier (one of) is required if it is mandatory for the specific bank, or if the TPP decides to pass in the debtor information.

initiation.creditorSepaAccount (object) or SepaInstantAccount (object) or FasterPaymentsAccount (object) or (ElixirAccount (PLAccount (object) or PLIbanAccount (object))) or (EUDomesticNonEuroAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object) or SENoBankIdCreditorAccount (object))) or (EUDomesticNonEuroInstantAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object) or SENoBankIdCreditorAccount (object))) or BankGiroAccount (object) or PlusGiroAccount (object) or VirtualAccount (object)(CreditorInformation)required

One of:

SEPA account details where the iban is required and the bic is optional.

initiation.creditor.ibanstringrequired

The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters.

Example: "GB29NWBK60161331926819"

initiation.creditor.bicstring

The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long.

Example: "BOFIIE2D"

initiation.creditor.namestringrequired

The owner's name for the creditor account. This parameter is not required for settlement accounts.

Example: "Customer Inc."

initiation.creditor.ultimateCreditorNamestring

The ultimate creditor's name.

Example: "Customer Inc."

initiation.creditor.addressobject(Address)

Address

initiation.creditor.bankNamestring

The creditor's bank name.

initiation.executionDatestring

This field specifies the future date for executing the payment in ISO 8601 format.". This field is optional and can only be used if the bank supports scheduled payments and the customer has permission to initiate future dated payments.

Example: "2023-04-29"

initiation.confirmFundsboolean

This field determines whether the bank will carry out a funds confirmation check before accepting the payment. Default = false.

Example: false

initiation.returnRefundAccountboolean

Supported banks will provide the debtor account details selected by the user during authorization. Default = false.

Example: false

initiation.disableFutureDatedPaymentConversionboolean

This field determines whether an auto-conversion of a single immediate payment to a future dated payment can be disabled. This may be required if the payment was initiated outside bank working hours. Default = false.

Example: false

initiation.callbackUrlstring

The TPP's url that Token.io calls back to. This url should not be under the token.io domain and must be https/SSL secure.
Note: If the callbackUrl is not provided, the PSU journey will end on the Token Payment Confirmation page

Example: "https://tpp.com/callback"

initiation.callbackStatestring(callbackStatev2)

The uniquely-generated string included as part of the URL when communicating with the bank. It is sent to the bank during payment initiation and is also returned in the callback from the bank. You can use it to identify which payment the callback refers to, ensuring that the callback can be reliably matched to the original payment request.

Example: "6242e45e-3063-4c42-8376"

initiation.chargeBearerstring(ChargeBearer)

The bearer of the charge, if any, for international transfers.

CRED - all charges are borne by the creditor.
DEBT - all charges are borne by the debtor.
SHAR - the parties share the charges.
SLEV - each party bears its own charges, recommended on SEPA payments.

Default "INVALID_CHARGE_BEARER"

Enum"INVALID_CHARGE_BEARER""CRED""DEBT""SHAR""SLEV"

Example: "CRED"

initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

initiation.flowTypestring(PaymentFlowType)required

The integration option requested by the TPP.

API_ONLY - This is the default. The TPP owns the user experience including bank selection logic, collection of mandatory fields, and embedded and decoupled authentication methods. This option is only used for API-only integrations.
FULL_HOSTED_PAGES - The TPP uses Token.io’s hosted pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience. This option is only used for Hosted Pages integrations.
EMBEDDED_HOSTED_PAGES - The TPP uses Token.io’s hosted pages to manage the credential collection (if relevant) of the payment initiation experience. bankId is required when EMBEDDED_HOSTED_PAGES is selected as the flowType. This option is only used for API-only integrations.
PAY_BY_LINK_HOSTED_PAGES - The TPP generates a secure payment link (redirect URL) that can be shared asynchronously (e.g., via email, SMS, or QR code). When the PSU opens the link, Token.io’s hosted pages handle the full payment experience, including collection of any missing mandatory information (such as amount or reference) and authentication. This option is used when payments are initiated via a shared link, enabling flexible and user-friendly account-to-account payment journeys.

Enum"API_ONLY""FULL_HOSTED_PAGES""EMBEDDED_HOSTED_PAGES""PAY_BY_LINK_HOSTED_PAGES"

Example: "FULL_HOSTED_PAGES"

initiation.payByLinkOptionsobject(PayByLinkOptions)

Optional Pay by Link settings. Used only when flowType = PAY_BY_LINK_HOSTED_PAGES.

pispConsentAcceptedboolean(pispConsentAccepted)

This flag indicates whether the user has granted consent for the payment in the TPP's user interface.

Default false

Example: false

initialEmbeddedAuthobject

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.

Example: {"username":"John Smith"}

curl -i -X POST \
  https://api.token.io/v2/payments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'request-timeout: 10' \
  -d '{
    "initiation": {
      "bankId": "ob-modelo",
      "refId": "9htio4a1sp2akdr1aa",
      "remittanceInformationPrimary": "Sweepco",
      "remittanceInformationSecondary": "Secondary remittance information.",
      "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
      "amount": {
        "value": "10.23",
        "currency": "EUR"
      },
      "localInstrument": "SEPA",
      "debtor": {
        "iban": "GB29NWBK60161331926819",
        "bic": "BOFIIE2D",
        "name": "John Smith",
        "ultimateDebtorName": "John Smith",
        "address": {
          "addressLine": [
            "The Coach House"
          ],
          "streetName": "221B",
          "buildingNumber": "2C",
          "postCode": "TR26 1EZ",
          "townName": "Saint Ives",
          "state": "Cornwall",
          "district": "string",
          "country": "GB"
        }
      },
      "creditor": {
        "iban": "GB29NWBK60161331926819",
        "bic": "BOFIIE2D",
        "name": "Customer Inc.",
        "ultimateCreditorName": "Customer Inc.",
        "address": {
          "addressLine": [
            "The Coach House"
          ],
          "streetName": "221B",
          "buildingNumber": "2C",
          "postCode": "TR26 1EZ",
          "townName": "Saint Ives",
          "state": "Cornwall",
          "district": "string",
          "country": "GB"
        },
        "bankName": "string"
      },
      "executionDate": "2023-04-29",
      "confirmFunds": false,
      "returnRefundAccount": false,
      "disableFutureDatedPaymentConversion": false,
      "callbackUrl": "https://tpp.com/callback",
      "callbackState": "6242e45e-3063-4c42-8376",
      "chargeBearer": "CRED",
      "risk": {
        "psuId": "0000789123",
        "paymentContextCode": "PISP_PAYEE",
        "paymentPurposeCode": "DVPM",
        "merchantCategoryCode": "4812",
        "beneficiaryAccountType": "BUSINESS",
        "contractPresentIndicator": true,
        "beneficiaryPrepopulatedIndicator": true,
        "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"
        }
      },
      "flowType": "FULL_HOSTED_PAGES",
      "payByLinkOptions": {
        "expiresDateTime": "2025-06-06T12:00:00Z"
      }
    },
    "pispConsentAccepted": false,
    "initialEmbeddedAuth": {
      "username": "John Smith"
    }
  }'

Responses

Successful response

Bodyapplication/json

paymentobject(Payment)

The payment object.

Response

application/json

{
  "payment": {
    "id": "pm:12345abcd:abcd",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "convertedToFutureDatedPayment": false,
    "refundDetails": { … },
    "status": "INITIATION_COMPLETED",
    "statusReasonInformation": "The payment is settled on the debtor side.",
    "bankPaymentStatus": "ACPC",
    "bankPaymentId": "1231423",
    "bankTransactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "authentication": { … },
    "createdDateTime": "2023-04-05T17:02:11.954Z",
    "updatedDateTime": "2023-04-05T17:02:11.954Z",
    "expiresDateTime": "2025-06-06T12:00:00Z",
    "errorInfo": { … },
    "paymentLinkStatus": "LINK_ACTIVE"
  }
}

Get payments

Request

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

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

idsArray 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

invertIdsboolean

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

statusesArray of strings(PaymentStatus)

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

Items Enum"INITIATION_PENDING""INITIATION_PENDING_REDIRECT_AUTH""INITIATION_PENDING_REDIRECT_AUTH_VERIFICATION""INITIATION_PENDING_REDIRECT_HP""INITIATION_PENDING_REDIRECT_PBL""INITIATION_PENDING_EMBEDDED_AUTH""INITIATION_PENDING_EMBEDDED_AUTH_VERIFICATION""INITIATION_PENDING_DECOUPLED_AUTH""INITIATION_PENDING_REDEMPTION""INITIATION_PENDING_REDEMPTION_VERIFICATION"

Example: statuses=INITIATION_COMPLETED&statuses=INITIATION_REJECTED

invertStatusesboolean

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

Example: invertStatuses=true

createdAfterstring

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

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

createdBeforestring

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

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

refIdsArray of strings

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

Example: refIds=ShBdcTeqFabqJJhUF&refIds=N5cJDFsQzVca3Q

onBehalfOfIdstring

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

Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7

refundStatusesArray 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

partialboolean

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

Example: partial=true

flowTypesArray of strings(PaymentFlowType)

Filters payments by their flow types - returns only payments with flow types listed in this parameter. Currently only supports PAY_BY_LINK_HOSTED_PAGES.

Items Value"PAY_BY_LINK_HOSTED_PAGES"

Example: flowTypes=PAY_BY_LINK_HOSTED_PAGES

curl -i -X GET \
  'https://api.token.io/v2/payments?limit=10&offset=LerV6Jmex&ids=pm2%3A4QExXrhKTxfShBdcTeqFabqJJhUF%3A2gFUX1NDgpN%2Cpm2%3AN5cJDFsQzVca3Qvr8kQocgEnjgX%3A2gFUX1NEdYA&invertIds=true&statuses=INITIATION_COMPLETED%2CINITIATION_REJECTED&invertStatuses=true&createdAfter=2022-04-05T17%3A00%3A00.000Z&createdBefore=2022-04-05T17%3A00%3A00.000Z&refIds=ShBdcTeqFabqJJhUF%2CN5cJDFsQzVca3Q&onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7&refundStatuses=PARTIAL%2CNONE&partial=true&flowTypes=PAY_BY_LINK_HOSTED_PAGES' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

paymentsArray of objects(Payment)required

payments[].idstringrequired

The Token.io generated payment id.

Example: "pm:12345abcd:abcd"

payments[].memberIdstring(memberId)required

The Token.io-assigned member id of the TPP.

Example: "m:123456abcd:abcd"

payments[].initiationPay By Link Flow Type (object) or Other Flow Types (object)(PaymentInitiation)required

One of:

The initiation payload for the payment. If the Flow Type is PAY_BY_LINK_HOSTED_PAGES — amount and remittanceInformationPrimary are optional

payments[].initiation.bankIdstring(bankId)

The Token.io id of the bank where the consent is created. This field is required if the customer is not using Token.io's Hosted Pages for bank selection, i.e., API-only integration when EMBEDDED_HOSTED_PAGES is selected in flowType, or Hosted Pages embedded (modal) integration.

Example: "ob-modelo"

payments[].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"

payments[].initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

payments[].initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

payments[].initiation.onBehalfOfIdstring

The id of the ultimate client on whose behalf the consent is created. If the consent is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

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

payments[].initiation.amountobject(Amount)

The transaction amount and currency.

payments[].initiation.localInstrumentstring(localInstrument)required

The bank's payment service used to make the payment.
Depending on which local instrument you select, you will require different account identifiers in the debtor and creditor objects. The creditor object is mandatory, but the debtor object is only required if it is mandatory for a specific bank. However, if the TPP decides to provide debtor details, account identifier field(s) within the debtor object are mandatory.
The fields within the creditor and debtor objects are populated as follows:

FASTER_PAYMENTS require the sortCode and accountNumber to be populated.
SEPA and SEPA_INSTANT require the iban, the bic is optional.
ELIXIR requires either the iban or the Polish domestic accountNumber, the bic is optional.
BANKGIRO requires the bankgiroNumber, the bic is optional.
PLUSGIRO requires the plusgiroNumber, the bic is optional.
EU_DOMESTIC_NON_EURO and EU_DOMESTIC_NON_EURO_INSTANT require either the iban or bban, the bic is optional, OR the bban is required and clearingNumber is optional. For an HP flow that doesn't have a preselected bankId, a SENoBankId account, where the currency is SEK or NOK, will require an iban and bban with an optional bic and/or clearingNumber.

Enum"SEPA""SEPA_INSTANT""FASTER_PAYMENTS""ELIXIR""EU_DOMESTIC_NON_EURO""EU_DOMESTIC_NON_EURO_INSTANT""BANKGIRO""PLUSGIRO"

Example: "SEPA"

payments[].initiation.debtorSepaAccount (object) or SepaInstantAccount (object) or FasterPaymentsAccount (object) or ElixirAccount (PLIbanAccount (object)) or (EUDomesticNonEuroAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object))) or (EUDomesticNonEuroInstantAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object))) or BankGiroAccount (object) or PlusGiroAccount (object)(DebtorInformation)

One of:

The debtor information. The account identifier (one of) is required if it is mandatory for the specific bank, or if the TPP decides to pass in the debtor information.

payments[].initiation.creditorSepaAccount (object) or SepaInstantAccount (object) or FasterPaymentsAccount (object) or (ElixirAccount (PLAccount (object) or PLIbanAccount (object))) or (EUDomesticNonEuroAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object) or SENoBankIdCreditorAccount (object))) or (EUDomesticNonEuroInstantAccount (EUIbanAccount (object) or BbanAccount (object) or ClearingNumberAccount (object) or SENoBankIdCreditorAccount (object))) or BankGiroAccount (object) or PlusGiroAccount (object) or VirtualAccount (object)(CreditorInformation)required

One of:

SEPA account details where the iban is required and the bic is optional.

payments[].initiation.creditor.ibanstringrequired

The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters.

Example: "GB29NWBK60161331926819"

payments[].initiation.creditor.bicstring

The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long.

Example: "BOFIIE2D"

payments[].initiation.creditor.namestringrequired

The owner's name for the creditor account. This parameter is not required for settlement accounts.

Example: "Customer Inc."

payments[].initiation.creditor.ultimateCreditorNamestring

The ultimate creditor's name.

Example: "Customer Inc."

payments[].initiation.creditor.addressobject(Address)

Address

payments[].initiation.creditor.bankNamestring

The creditor's bank name.

payments[].initiation.executionDatestring

This field specifies the future date for executing the payment in ISO 8601 format.". This field is optional and can only be used if the bank supports scheduled payments and the customer has permission to initiate future dated payments.

Example: "2023-04-29"

payments[].initiation.confirmFundsboolean

This field determines whether the bank will carry out a funds confirmation check before accepting the payment. Default = false.

Example: false

payments[].initiation.returnRefundAccountboolean

Supported banks will provide the debtor account details selected by the user during authorization. Default = false.

Example: false

payments[].initiation.disableFutureDatedPaymentConversionboolean

This field determines whether an auto-conversion of a single immediate payment to a future dated payment can be disabled. This may be required if the payment was initiated outside bank working hours. Default = false.

Example: false

payments[].initiation.callbackUrlstring

The TPP's url that Token.io calls back to. This url should not be under the token.io domain and must be https/SSL secure.
Note: If the callbackUrl is not provided, the PSU journey will end on the Token Payment Confirmation page

Example: "https://tpp.com/callback"

payments[].initiation.callbackStatestring(callbackStatev2)

The uniquely-generated string included as part of the URL when communicating with the bank. It is sent to the bank during payment initiation and is also returned in the callback from the bank. You can use it to identify which payment the callback refers to, ensuring that the callback can be reliably matched to the original payment request.

Example: "6242e45e-3063-4c42-8376"

payments[].initiation.chargeBearerstring(ChargeBearer)

The bearer of the charge, if any, for international transfers.

CRED - all charges are borne by the creditor.
DEBT - all charges are borne by the debtor.
SHAR - the parties share the charges.
SLEV - each party bears its own charges, recommended on SEPA payments.

Default "INVALID_CHARGE_BEARER"

Enum"INVALID_CHARGE_BEARER""CRED""DEBT""SHAR""SLEV"

Example: "CRED"

payments[].initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

payments[].initiation.flowTypestring(PaymentFlowType)required

The integration option requested by the TPP.

API_ONLY - This is the default. The TPP owns the user experience including bank selection logic, collection of mandatory fields, and embedded and decoupled authentication methods. This option is only used for API-only integrations.
FULL_HOSTED_PAGES - The TPP uses Token.io’s hosted pages to manage the full bank selection and credential collection (if relevant) of the payment initiation experience. This option is only used for Hosted Pages integrations.
EMBEDDED_HOSTED_PAGES - The TPP uses Token.io’s hosted pages to manage the credential collection (if relevant) of the payment initiation experience. bankId is required when EMBEDDED_HOSTED_PAGES is selected as the flowType. This option is only used for API-only integrations.
PAY_BY_LINK_HOSTED_PAGES - The TPP generates a secure payment link (redirect URL) that can be shared asynchronously (e.g., via email, SMS, or QR code). When the PSU opens the link, Token.io’s hosted pages handle the full payment experience, including collection of any missing mandatory information (such as amount or reference) and authentication. This option is used when payments are initiated via a shared link, enabling flexible and user-friendly account-to-account payment journeys.

Enum"API_ONLY""FULL_HOSTED_PAGES""EMBEDDED_HOSTED_PAGES""PAY_BY_LINK_HOSTED_PAGES"

Example: "FULL_HOSTED_PAGES"

payments[].initiation.payByLinkOptionsobject(PayByLinkOptions)

Optional Pay by Link settings. Used only when flowType = PAY_BY_LINK_HOSTED_PAGES.

payments[].convertedToFutureDatedPaymentboolean

This field indicates whether a payment has been converted from a single immediate payment to a future dated payment. This can happen if the payment is initiatied outside bank working hours and paymentInitiation.disableFutureDatedPaymentConversion = false.

Default false

Example: false

payments[].refundDetailsobject(RefundDetails)

The refund-related information for this payment. This field requires specific permission and is only available if paymentInitiation.returnRefundAccount is set to true.

payments[].statusstring(PaymentStatus)required

The Token.io Payment Status:

INITIATION_PENDING - Token.io has received the payment initiation and the initiation has passed Token.io's validation. No action is required; await the bank's response for the next step, e.g., a webhook with the status update, or poll the payment.
INITIATION_PENDING_REDIRECT_AUTH - The payment request has been acknowledged by the bank and Token.io is awaiting user confirmation on the bank's page. If Token.io's Hosted Pages is not in use, you'll need to redirect the user to the url found in the authentication field and await a callback from the bank (if you're handling callbacks) or from Token.io (if Token.io handles the callbacks for you).
INITIATION_PENDING_REDIRECT_PBL – The payment session has been initialized and the PSU has opened the Pay by Link URL. At this stage, Token.io’s Hosted Pages will collect any missing mandatory information (such as amount or reference) from the user before continuing with the payment initiation process.
INITIATION_PENDING_REDIRECT_AUTH_VERIFICATION - Token.io has received the callback information from the bank and is currently verifying it with the bank. No action is required; await the bank's response for the next step, e.g., a webhook with the status update, or poll the payment.
INITIATION_PENDING_REDIRECT_HP - This status can only be observed if you're using Token.io's Hosted Pages. You'll need to redirect the user to the url found in the authentication field and await a callback from Token.io's Hosted Pages after Token.io handles the entire flow for you.
INITIATION_PENDING_EMBEDDED_AUTH - Token.io is waiting for the requested input from the user. If Token.io's Hosted Pages is not in use, you must provide the requested information to process the payment. Required information can be found in the authentication object of the payment.
INITIATION_PENDING_EMBEDDED_AUTH_VERIFICATION - Token.io is waiting for the bank to process the provided information. No action is required; await the bank's response for the next step, e.g., a webhook with the status update, or poll the payment.
INITIATION_PENDING_DECOUPLED_AUTH - Token.io is polling status from the bank while the user authenticates in a decoupled way. No action is required; await the bank's response for the next step, e.g., a webhook with the status update, or poll the payment.
INITIATION_PENDING_REDEMPTION - The payment is ready for a redemption. No action is required; await the bank's response for the next step, e.g., a webhook with the status update, or poll the payment.
INITIATION_PENDING_REDEMPTION_VERIFICATION - Token.io is waiting for the bank to redeem the payment. No action is required; await the bank's response for the next step, e.g., a webhook with the status update, or poll the payment.
INITIATION_PROCESSING - The payment initiation request has been acknowledged by the bank and is now being processed. No action is required; await the bank's response for the next step, e.g., a webhook with the status update, or a polling call. If necessary wait for additional webhooks to be sent. If a webhook is not received, then use a polling call every 120 min. The status can be updated to one of INITIATION_COMPLETED, INITIATION_REJECTED, INITIATION_NO_FINAL_STATUS_AVAILABLE or INITIATION_EXPIRED (if the status polling period is exhausted).
INITIATION_COMPLETED - The final status (usually) indicating that the payment initiation request has been successfully completed. This doesn't guarantee that the payment is settled.
INITIATION_REJECTED - The final status indicating that the payment initiation request has been rejected by the bank. More details are shared in the corresponding statusReasonInformation field.
INITIATION_REJECTED_INSUFFICIENT_FUNDS - The final status indicating that the payment initiation request has been rejected due to insufficient funds.
INITIATION_FAILED - The final status indicating that Token.io failed to proceed with the initiation due to problems with reaching the bank, or because payment authentication has not been completed within the allowed time period. More details are shared in the corresponding statusReasonInformation field.
INITIATION_DECLINED - The final status indicating that the payment initiation request has been declined, in most cases actively by the user.
INITIATION_EXPIRED - The final status, indicating that the bank has not responded to the payment initiation request within the allowed time period.
INITIATION_NO_FINAL_STATUS_AVAILABLE - Payment status has not been updated for some time and Token.io has given up polling it. This is a final status, but it does not indicate success or failure. Please contact the bank to check the actual status of the payment.
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 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.
CANCELED – The final status indicating that the payment has been canceled.

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 INITIATION_COMPLETED.
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"INITIATION_PENDING""INITIATION_PENDING_REDIRECT_AUTH""INITIATION_PENDING_REDIRECT_AUTH_VERIFICATION""INITIATION_PENDING_REDIRECT_HP""INITIATION_PENDING_REDIRECT_PBL""INITIATION_PENDING_EMBEDDED_AUTH""INITIATION_PENDING_EMBEDDED_AUTH_VERIFICATION""INITIATION_PENDING_DECOUPLED_AUTH""INITIATION_PENDING_REDEMPTION""INITIATION_PENDING_REDEMPTION_VERIFICATION"

Example: "INITIATION_COMPLETED"

payments[].statusReasonInformationstring

A human-readable description of the reason for the reported status, which may include a message from the bank. This value should not exceed 256 characters in length.

Example: "The payment is settled on the debtor side."

payments[].bankPaymentStatusstring

The raw bank status. This can be the ISO 20022 payment status code. See ISO 20022 payment status codes for more information. This field can be empty if no payment status is available on bank side.

Example: "ACPC"

payments[].bankPaymentIdstring

The payment id from the bank. Not all banks provide this. This field can be left empty if information is not available from the bank side.

Example: "1231423"

payments[].bankTransactionIdstring

The transaction id from the bank when the transaction is settled. Not all banks provide this. This field can be left empty if information is not available from the bank.

Example: "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV"

payments[].authenticationRedirectUrl (object) or EmbeddedAuth (object)(Authenticationv2)

One of:

The authentication operation required to proceed with payment creation. This is present when additional steps are required to authorize the payment.

payments[].createdDateTimestringrequired

The date and time this payment object was created (in ISO 8601 format).

Example: "2023-04-05T17:02:11.954Z"

payments[].updatedDateTimestringrequired

The date and time this payment object was last updated (in ISO 8601 format).

Example: "2023-04-05T17:02:11.954Z"

payments[].expiresDateTimestring

The UTC date and time when the payment link will expire. This field is only returned when the flow type is PAY_BY_LINK_HOSTED_PAGES (in ISO 8601 format).

Example: "2025-06-06T12:00:00Z"

payments[].errorInfoobject(errorInfo)

This field will be populated if the status is final and the payment is not successful, or there has been an error that caused payment rejection, or the bank could not be reached to get a status update.

payments[].paymentLinkStatusstring(PaymentLinkStatus)

If the payment was initiated using a Pay by Link flow type, this shows the status of the payment link. For all other flows, this field is empty.

LINK_ACTIVE – The payment link is active and can be used to initiate a payment.
LINK_EXPIRED – The payment link has expired and can no longer be used.
LINK_CANCELED – The payment link has been canceled by the TPP or system and cannot be used.
LINK_REDEEMED – The payment link has been redeemed and the payment has been initiated.

Enum"LINK_ACTIVE""LINK_EXPIRED""LINK_CANCELED""LINK_REDEEMED"

Example: "LINK_ACTIVE"

pageInfoobject(PageInfo)required

The information about the current page, which also indicates whether the next page exists.

pageInfo.limitinteger(int32)[ 1 .. 200 ]required

The limit (maximum number of objects to return) applied to this page.
The default and maximum allowed limit is 200. If this limit is exceeded, was not set or was set to 0, it will be set to 200.

Default 200

Example: 20

pageInfo.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 is 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 the dynamic nature of the data.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "LerV6Jmex"

pageInfo.nextOffsetstring

The offset for the next page. If the page is empty, it is equal to this page offset. If the page is not empty, but there are no more objects to load (haveMore = false), it will be empty.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "KgwG8Qkat"

pageInfo.haveMoreboolean

This field indicates whether there are more objects to load, i.e. whether the next page exists.

Default false

Example: false

Response

application/json

{
  "payments": [
    { … }
  ],
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  }
}

Get a payment

Request

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.

Security

Bearer or BasicAuth

Path

paymentIdstringrequired

The payment id.

Headers

request-timeoutinteger

Sets the number of elapsed seconds until Token.io sends the response back, even if the call is not finished by that time (in which case the call will be completed asynchronously).

Example: 10

curl -i -X GET \
  'https://api.token.io/v2/payments/{paymentId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'request-timeout: 10'

Responses

Successful response

Bodyapplication/json

paymentobject(Payment)

The payment object.

Response

application/json

{
  "payment": {
    "id": "pm:12345abcd:abcd",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "convertedToFutureDatedPayment": false,
    "refundDetails": { … },
    "status": "INITIATION_COMPLETED",
    "statusReasonInformation": "The payment is settled on the debtor side.",
    "bankPaymentStatus": "ACPC",
    "bankPaymentId": "1231423",
    "bankTransactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "authentication": { … },
    "createdDateTime": "2023-04-05T17:02:11.954Z",
    "updatedDateTime": "2023-04-05T17:02:11.954Z",
    "expiresDateTime": "2025-06-06T12:00:00Z",
    "errorInfo": { … },
    "paymentLinkStatus": "LINK_ACTIVE"
  }
}

Cancel a payment

Request

The DELETE /v2/payments/{paymentId} endpoint allows you to cancel a payment that was created with the POST /v2/payments endpoint. This is useful if the payment is no longer needed.

Security

Bearer or BasicAuth

Path

paymentIdstring(uuid)required

The payment id.

curl -i -X DELETE \
  'https://api.token.io/v2/payments/{paymentId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

paymentobject(Payment)

The payment object.

Response

application/json

{
  "payment": {
    "id": "pm:12345abcd:abcd",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "convertedToFutureDatedPayment": false,
    "refundDetails": { … },
    "status": "CANCELED",
    "authentication": { … },
    "createdDateTime": "2023-04-05T17:02:11.954Z",
    "updatedDateTime": "2023-04-05T17:02:11.954Z",
    "errorInfo": { … },
    "paymentLinkStatus": "LINK_CANCELED"
  }
}

Provide information for embedded authentication

Request

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.

Security

Bearer or BasicAuth

Path

paymentIdstringrequired

The payment id.

Headers

request-timeoutinteger

Sets the number of elapsed seconds until Token.io sends the response back, even if the call is not finished by that time (in which case the call will be completed asynchronously).

Example: 10

Bodyapplication/jsonrequired

embeddedAuthobject(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.

Example: {"123":"SMS message"}

curl -i -X POST \
  'https://api.token.io/v2/payments/{paymentId}/embedded-auth' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'request-timeout: 10' \
  -d '{
    "embeddedAuth": {
      "123": "SMS message"
    }
  }'

Responses

Successful response

Bodyapplication/json

paymentobject(Payment)

The payment object.

Response

application/json

{
  "payment": {
    "id": "pm:12345abcd:abcd",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "convertedToFutureDatedPayment": false,
    "refundDetails": { … },
    "status": "INITIATION_COMPLETED",
    "statusReasonInformation": "The payment is settled on the debtor side.",
    "bankPaymentStatus": "ACPC",
    "bankPaymentId": "1231423",
    "bankTransactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
    "authentication": { … },
    "createdDateTime": "2023-04-05T17:02:11.954Z",
    "updatedDateTime": "2023-04-05T17:02:11.954Z",
    "expiresDateTime": "2025-06-06T12:00:00Z",
    "errorInfo": { … },
    "paymentLinkStatus": "LINK_ACTIVE"
  }
}

Generate QR code

Request

The GET /qr-code endpoint generates a QR code in fixed SVG format (240x240 px). This allows TPPs to programmatically obtain a scannable QR code .

Security

Bearer or BasicAuth

Query

datastringrequired

The encoded URL to use while generating the QR code. The link must be URL encoded.

curl -i -X GET \
  'https://api.token.io/qr-code?data=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

QR code successfully generated

Bodyimage/svg+xml

string

The QR code in SVG format.

Response

image/svg+xml

<svg xmlns="http://www.w3.org/2000/svg" width="240" height="240" viewBox="0 0 240 240">
    <!-- more SVG content here -->
</svg>

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

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

Initiate a payment

RequestExpand all

Responses

Get payments

Request

Responses

Get a payment

Request

Responses

Cancel a payment

Request

Responses

Provide information for embedded authentication

Request

Responses

Generate QR code

Request

Responses

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

Authentication keys

Reports

Webhooks

Request