Skip to content
Get started
/
/
Payment rails
Last updated

Payment rails

Payment rails supported by Token.io and examples of their use are detailed below.

Supported rails for Payments v2

The following table lists the various payment rails currently supported by Token.io for Payments v2 and the respective routing information required.

Payment railFields to setCountry/AreaSupported by Token.io?
SEPA• IBAN
• BIC		EuropeSupported
SEPA Instant• IBAN
• BIC		EuropeSupported
Faster Payments Service (FPS)• Sort code
• Account number		UKSupported
Elixir• IBAN
• BIC
or
• Account number
• BIC		PolandSupported
EU Domestic Non Euro• IBAN
• BIC
or
• BBAN
• BIC/Clearing number		EU domestic payments systemsSupported
EU Domestic Non Euro Instant• IBAN
• BIC
or
• BBAN
• BIC/Clearing number		EU domestic payments systemsSupported
Bankgiro• Bankgiro number
• BIC		SwedenIn development
PlusGiro• PlusGiro number
• BIC		SwedenIn development

Supported rails for Payments v1

The following table lists the various payment rails currently supported by Token.io for Payments v1 and the respective routing information required.

Payment railFields to setCountry/AreaSupported by Token.io?
SEPA• IBAN
• BIC (optional)		EuropeSupported
SEPA Instant• IBAN
• BIC (optional)		EuropeSupported
Faster Payments Service (FPS)• Sort code
• Account number		UKSupported
Elixir• IBAN
• BIC (optional)
or
• Account number
• BIC (optional)		PolandSupported
EU Domestic Non Euro• IBAN • BIC (optional)
or
• BBAN
• BIC/Clearing number (optional)		EU domestic payments systemsSupported
EU Domestic Non Euro Instant• IBAN
• BIC (optional)
or
• BBAN
• BIC/Clearing number (optional)		EU domestic payments systemsSupported
Bankgiro• Bankgiro number
• BIC (optional)		SwedenIn development
PlusGiro• PlusGiro number
• BIC (optional)		SwedenIn development

Payments v2 use cases: which payment rail should I use?

Some objects and fields in a payment request are common to all banks. Others are bank-dependent, like the payment rails supported by a bank. The information requirements imposed by different countries can vary as well. In general, there are two primary use cases for A2A payment initiation: domestic payments and international payments.

A domestic payment transfers money from a payer's bank account to the recipient's bank account within the same country. Interbank transfers within the same country can use one or more domestic payment systems operated and administered within that country, depending on the type and volume of the transaction. For instance, FPS is a domestic payment system in the UK, as seen in the Beneficiary accounts table above. Elixir is a domestic payment system in Poland.

International payments are those where the payee and the recipient are in different countries. However, with the advent of the single euro payments market, SEPA makes it possible for retail transactions to directly debit accounts in another SEPA member country, as well as to receive direct deposit payments and pay bills by electronic transfer from another member country, but only for transactions in euros. SEPA is ruled out as a payment method when a non-euro currency is involved on either side (or both sides) of the transaction, even between SEPA member countries.

The TPP handling the transfer will need to specify, at minimum, the following information in the API request payload:

  • a unique TPP-generated reference identifier (refId)

  • remittance information (remittanceInformationPrimary) containing a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent

  • the amount (currency and value)

  • the payment rail (localInstrument), e.g., SEPA

  • creditor details; these will depend on the destination account (SEPA or FPS), but will include the name of the payee/creditor and the beneficiary account details

  • the execution date (executionDate), required only if you want the transfer to take place in the future, rather than immediately

  • a redirect URL (callbackUrl), the address where the TPP wants the user redirected after authentication and consent

  • any information required by the bank in mandatoryFields when the source bank is selected by the user. These fields are entirely bank-dependent, see Mandatory Fields for details

For debtor details, the debtor object is optional. Within the debtor object name and ultimateDebtorName are optional. If debtor information is provided, account identifiers are required, these will depend on the localInstrument used. See the POST /v2/payments endpoint for more details.

You can provide more information for traceability and reconciliation in accordance with your business practices (see the Token.io API reference for the complete set of options), but the list above contains the essentials.

To help you in determining the appropriate payment method/system to use in a payment request, here are some examples of general use cases for single immediate payments, with the minimal required request payload for each. Other cases can then be extrapolated and modelled based on these examples.

Send GBP from UK to UK

Here, we're initiating an interbank transfer between banks which are both located in the UK using Faster Payments (FASTER_PAYMENTS).

POST {{BASE_URL}}/v2/payments

{
    "initiation": {
        "refId": "xyztyuberty",
        "remittanceInformationPrimary": "RemittancePrimary",
        "amount": {
            "value": "225.00",
            "currency": "GBP"
        },
        "localInstrument": "FASTER_PAYMENTS",
        "creditor": {
            "accountNumber": "12345678",
            "sortCode: "123456",
        },
        "redirectUrl": "https://sport-merchant.com/payment"
    }
}

The response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

Send EUR from EU to EU

This case initiates an interbank transfer between banks both located within the EU. If both banks support SEPA Instant (sometimes called SCT Inst) and this is an urgent SIP, SEPA_INSTANT should be specified as the payment rail. If either the sending or receiving bank doesn't support SCT Inst, you'll need to specify standard SEPA. Here's a request payload example with SEPA_INSTANT:

POST {{BASE_URL}}/v2/payments

{
    "initiation": {
        "refId": "xyztyuberty",
        "remittanceInformationPrimary": "RemittancePrimary",
        "amount": {
            "value": "125.00",
            "currency": "EUR"
        },
        "localInstrument": "SEPA_INSTANT",
        "creditor": {
            "iban: "FR142004010050500013M02606",
        },
        "redirectUrl": "https://lauberge-serene.com/payment"
    }
}

As in the previous example, the response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

Send HUF from Hungary to Hungary

This case initiates an interbank transfer between banks located within Hungary. This uses the EU domestic non- Euro payment rail with the payee's BBAN:

POST {{BASE_URL}}/v2/payments

{
    "initiation": {
        "refId": "xyztyuberty",
        "remittanceInformationPrimary": "RemittancePrimary",
        "amount": {
            "value": "89.99",
            "currency": "HUF"
        },
        "localInstrument": "EU_DOMESTIC_NON_EURO",
        "creditor": {
            "bban: "117730161111101800001234",
        },
        "redirectUrl": "https://menedekhely.com/payment"
    }
}

As in the previous example, the response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

Send SEK from Sweden to Sweden

This case initiates an interbank transfer between banks located within Sweden. This uses the EU domestic non- Euro payment rail with the payee's IBAN:

POST {{BASE_URL}}/v2/payments

{
    "initiation": {
        "refId": "xyztyuberty",
        "remittanceInformationPrimary": "RemittancePrimary",
        "amount": {
            "value": "1250.00",
            "currency": "SEK"
        },
        "localInstrument": "EU_DOMESTIC_NON_EURO",
        "creditor": {
            "iban: "SE4550000000058398257466",
        },
        "redirectUrl": "https://mobel.com/payment"
    }
}

As in the previous example, the response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

Send PLN from Poland to Poland

This case initiates an interbank transfer between banks located within Poland. This uses the Elixir payment rail with the payee's Elixir-registered bank account number:

POST {{BASE_URL}}/v2/payments

{
    "initiation": {
        "refId": "xyztyuberty",
        "remittanceInformationPrimary": "RemittancePrimary",
        "amount": {
            "value": "75.00",
            "currency": "PLN"
        },
        "localInstrument": "ELIXIR",
        "creditor": {
            "accountNumber: "0000071219812874",
        },
        "redirectUrl": "https://strojsportowy.com/payment"
    }
}

As in the previous example, the response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

Payments v1 use cases: which payment rail should I use?

Some objects and fields in a payment request are common to all banks. Others are bank-dependent, like the payment rails supported by a bank. The information requirements imposed by different countries can vary as well. In general, however, there are two primary use cases for Account-to-Account payment initiation: domestic payments and international payments, although even here certain nuances may apply.

A domestic payment transfers money from a payer's bank account to the recipient's bank account within the same country. Interbank transfers within the same country can use one or more domestic payment systems operated and administered within that country, depending on the type and volume of the transaction. For instance, FPS is a domestic payment system in the UK, as seen in the Beneficiary accounts table above. Elixir is a domestic payment systems in Poland.

Cross-border payments happen when the payee and the recipient are in different countries. However, with the advent of the single euro payments market, SEPA makes it possible for retail transactions to directly debit accounts in another SEPA member country, as well as to receive direct deposit payments and pay bills by electronic transfer from another member country, but only for euro-denominated transactions. SEPA is ruled out as a payment method when a non-euro currency is involved on either side (or both sides) of the transaction, even between SEPA member countries.

Based on these assumptions, the TPP handling this transfer will need to specify, at minimum, the following information in its API request payload:

  • a unique TPP-generated reference identifier (refId), identifying the request

  • the TPP to whom the money is being paid, identified by its Token.io member ID

  • the payment details

  • currency

  • amount

  • execution date (required only if you want the transfer to take place in the future, rather than immediately)

  • destination – the beneficiary account details: SEPA, and the legal name of the payee/creditor

  • a redirect URL – address where the TPP wants its user redirected after authentication and consent

  • any information required by the bank in mandatoryFields when the source bank is selected by the user. These fields are entirely bank-dependent. See Mandatory fields for details.

  • a description of the payment – an identifier that will be used for reconciliation when funds are cleared within beneficiary’s account

You can provide more information for traceability and reconciliation in accordance with your business practices (the Token.io API Definition for the complete set of options), but the list above contains the essentials. In our payload example, we will omit any providerTransferMetadata the bank may or may not require. These metadata are based on the API standard adopted by the particular bank — CMA9, NextGenPSD2, PolishAPI, or STET — and typically contain debtor/creditor identifiers and regulatory reporting codes for international payments.

To help you in determining the appropriate payment method/system to use in a payment request, let's explore a number of general use cases for single immediate payment and what the minimally required request payload looks like for each. Other cases can then be extrapolated and modeled based on these examples.

Send GBP from UK to UK

Here, we're initiating an interbank transfer between banks which are both located in the UK. If this is an urgent SIP, you'll want to use Faster Payments (fasterPayments).

POST {{BASE_URL}}/token-requests

{
    "requestPayload": {
        "refId": "bksrtywer", // TPP-generated reference ID
        "to": {
            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // Member ID of the TPP initiating the request
        },
        "transferBody": {
            "currency": "GBP",
            "lifetimeAmount": "100.00",
            "transferInstructions": {
                "transferDestinations": {
                     "fasterPayments": {
                         "accountNumber": "555555555", // payee's IBAN
                         "sortCode": "200415" // payee's BIC code
                     }
                }
            }
        },
        "description": "Online purchase",
        "redirectUrl": "https://sample-merchant-domain.com/transfer"
    }
}

Yet again, as in the previous examples, the response payload from the bank via Token.io for a successful request will contain a request id that uniquely identifies this transfer request, along with a duplicate of the request payload received, confirming its details.

Send EUR from EU to EU

This case initiates an interbank transfer between banks both located within the EU. If both banks support SEPA Instant (sometimes called SCT Inst) and this is an urgent SIP, sepaInstant should be specified as the payment rail. If either the sending or receiving bank doesn't support SCT Inst, you'll need to specify standard sepa. Here's a request payload example:

POST {{BASE_URL}}/token-requests

{
    "requestPayload": {
        "refId": "lkjhgffds", // TPP-generated reference ID
        "to": {
            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // Member ID of the TPP initiating the request
        },
        "transferBody": {
            "currency": "EUR",
            "lifetimeAmount": "500",
            "transferInstructions": {
                "transferDestinations": {
                     "sepa": {
                         "iban": "FR14 2004 1010 0505 0001 3M02 606", // payee's IBAN
                     }
                }
            }
        },
        "description": "Online purchase",
        "redirectUrl": "https://sample-merchant-domain.com/transfer"
    }
}

As in the previous examples, the response payload from the bank via Token.io for a successful request will contain a request id that uniquely identifies this transfer request, along with a duplicate of the request payload received, confirming its details.

Send HUF from Hungary to Hungary

This case initiates an interbank transfer between banks located within Hungary. This uses the EU domestic non-Euro payment rail with the payee's BBAN:

POST {{BASE_URL}}/token-requests

{
    "requestPayload": {
        "refId": "bksrtywer", // TPP-generated reference ID
        "to": {
            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // Member ID of the TPP initiating the request
        },
        "transferBody": {
            "currency": "HUF",
            "lifetimeAmount": "89.99",
            "transferInstructions": {
                "transferDestinations": {
                     "euDomesticNonEuro": {
                         "bban": "117730161111101800001234", // payee's BBAN
                     }
                }
            }
        },
        "description": "Hotel",
        "redirectUrl": "https://menedekhely.com/transfer"
    }
}

As in the previous example, the response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

Send SEK from Sweden to Sweden

This case initiates an interbank transfer between banks located within Sweden. This uses the EU domestic non-Euro payment rail with the payee's IBAN:

POST {{BASE_URL}}/token-requests

{
    "requestPayload": {
        "refId": "bksrtywer", // TPP-generated reference ID
        "to": {
            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // Member ID of the TPP initiating the request
        },
        "transferBody": {
            "currency": "SEK",
            "lifetimeAmount": "1250.00",
            "transferInstructions": {
                "transferDestinations": {
                     "euDomesticNonEuro": {
                         "iban": "SE4550000000058398257466", // payee's IBAN
                     }
                }
            }
        },
        "description": "Furniture",
        "redirectUrl": "https://mobel.com/transfer"
    }
}

As in the previous example, the response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

Send PLN from Poland to Poland

This case initiates an interbank transfer between banks located within Poland. This uses the Elixir payment rail with the payee's Elixir-registered bank account number:

POST {{BASE_URL}}/token-requests

{
    "requestPayload": {
        "refId": "lkjhgffds", // TPP-generated reference ID
        "to": {
            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // Member ID of the TPP initiating the request
        },
        "transferBody": {
            "currency": "PLN",
            "lifetimeAmount": "75.00",
            "transferInstructions": {
                "transferDestinations": {
                     "elixir": {
                        "accountNumber: "0000071219812874", // payee's Polish bank account number
                     }
                }
            }
        },
        "description": "Sportswear",
        "redirectUrl": "https://strojsportowy.com/transfer"
    }
}

As in the previous example, the response payload from the bank via Token.io for a successful request will contain a payment id that uniquely identifies this request, along with details of the request payload received.

If you have any feedback about the developer documentation, please contact devdocs@token.io

Previous page
Next page
© 2025 TOKEN, INC. ALL RIGHTS RESERVED.