Initiating Payment

Currently, the Token API supports payment initiation for the following transaction categories:

Each flow is covered in more detail in the topics links above. But, before delving deeperinto the payment flows, there are some general concepts with which to become familiar. Obviously, only banks supporting the transaction category (single, future-dated, recurring) requested by the user should be displayed to the user for selection after appropriate filtering of the GET /banks payload.

Additionally, in the parlance of Open Banking, "payments" are often referred to as "transfers" because the PSUClosedPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both. is requesting that money be moved from one place to another. How and where it is transferred are called "beneficiary account details." Via the API, a TPP passes this information to its PSU's selected bank at the time of payment initiation. Money can be moved by the bank via domestic payment systems, SEPAClosedSingle Euro Payments Area – a payments system created by the European Union (EU) which harmonizes the way cashless payments transact between euro countries. European consumers, businesses, and government agents who make payments by direct debit, instant credit transfer, and through credit transfers use the SEPA architecture. The single euro payment area is approved and regulated by the European Commission. SEPA currently includes 36 members. It encompasses the 28 EU member states along with Iceland, Norway, Liechtenstein, Switzerland, Andorra, Vatican City, Monaco and San Marino. The single euro payment area remains an ongoing, collaborative process between these parties. SEPA is in the process of harmonizing rules regarding mobile and online payments. SCTClosedSEPA Instant Credit Transfer – Electronic retail payments processed in real time, 24 hours a day, 365 days a year; funds are made available immediately for use by the recipient., or the cross-border payment systems supported.

Supported Payment Systems (Rails)

The following table lists the various payment systems currently supported by the Token API and the respective routing information required.

Beneficiary Account Details
Payment System Fields to Set Applicable Country/Area Supported by Token?
SEPAClosedSingle Euro Payments Area – a payments system created by the European Union (EU) which harmonizes the way cashless payments transact between euro countries. European consumers, businesses, and government agents who make payments by direct debit, instant credit transfer, and through credit transfers use the SEPA architecture. The single euro payment area is approved and regulated by the European Commission. SEPA currently includes 36 members. It encompasses the 28 EU member states along with Iceland, Norway, Liechtenstein, Switzerland, Andorra, Vatican City, Monaco and San Marino. The single euro payment area remains an ongoing, collaborative process between these parties. SEPA is in the process of harmonizing rules regarding mobile and online payments. IBANClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself.
BICClosedBank Identifier Code – a unique identifier for a specific financial institution. A BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code.

Europe

Supported
SEPA InstantClosedEuro credit transfers with the funds made available on the account in less than ten seconds at any time and in an area that will progressively span over 27 EU countries and an additional 17 non-EU countries, autonomous regions and territories. • IBAN
• BIC
Europe Supported
Faster PaymentsClosedUK banking initiative to reduce payment times between different banks' customer accounts down to a few seconds from the three working days transfer time imposed under the BACS system. SORT codeClosedNumber code used by British and Irish banks using six digits divided into three different pairs; for instance, 12-34-56. These codes, like many other bank codes, are used to identify the location of the bank where the account is held. The first two digits are usually bank identifiers. However, in some cases, the first code may describe the bank as well. It must be noted that the SORT code of a bank is integrated and encoded in the IBAN number of the account but not in the BIC codes of the account. A SORT code is used by banks to identify and route the money transfers to the respective bank and account. SORT codes are also called NSC or National SORT Code in Ireland and are regulated by the IPSO (Irish Payment Services Organization). A SORT Code in Ireland begins with the digit “9”.
• Account number
UK Supported
CHAPSClosedClearing House Automated Payments System – used by large financial institutions that need to transfer billions of dollars worth of currency each day. To assist in these transfers, CHAPS enables real-time fund transfers and can accommodate frequent large transfers with virtually no delay. The speed of CHAPS also substantially eliminates the risk that senders will cancel their transfers before they are accepted by the recipient. CHAPS is administered by the Bank of England (BoE) and is used by 30 participating financial institutions. Approximately 5,500 additional institutions also engage with the system by way of partnership agreements with the 30 primary members. • SORT code
• Account number
UK Supported
BACSClosedBankers Automated Clearing Services – an electronic payment made directly from one UK bank account to another, taking up to three working days to arrive. There are two main types of Bacs payment - Direct Credit, which is a bank transfer, and Direct Debit, where one party automatically takes payment from another party’s account with their authorisation. • SORT code
• Account number
UK Supported
ElixirClosedA payments system that ensures electronic interbank settlement in Poland. Transactions directed to the system are settled within one of three Elixir sessions held each business day and closed on the same day in the National Bank of Poland's SORBNET2 system, which guarantees interbank transfer of funds. IBAN is sent as account number for domestic currency payment initiation Poland Supported
Elixir Express ClosedAn instant payment clearing system in Poland which allows the direct execution of the transaction from the payer's account in one bank to the payee's account in another bank. It supports transaction settlement in near real time, without any intermediary institutions. Account number Poland Not Supported
Blue CashClosedAn alternative to Express Elixir, the Blue Cash system does not have one dedicated account common to all participants. Instead, interbank transfers are executed on special intermediate accounts. (SPBC) IBAN is sent as account number for domestic currency payment initiation Poland Supported
SORBNETClosedPoland's national RTGS system for high-value and urgent domestic payments. RTGS stands for real-time gross settlement, a continuous process of settling payments on an individual order basis without netting debits with credits across the books of a central bank (i.e., transaction bundling). SORBNET is owned and operated by the National Bank of Poland (NBP). It has 50 direct participants. IBAN is sent as account number for domestic currency payment initiation Poland Supported
TARGET2ClosedOwned and operated by the Eurosystem, TARGET2 is the real-time gross settlement (RTGS) system with payment transactions settled one by one on a continuous basis in central bank money with immediate finality. There is no upper or lower limit on the value of payments. TARGET2 mainly settles operations of monetary policy and money market operations. IBAN EU Supported
HSVPClosedA real-time gross settlement system (RTGS) for large and time-sensitive transactions, as well as multilateral netting for small value payments. HSVP is owned and operated by the Croatian central bank (Hrvatska narodna banka, or HNB). IBAN Croatia Supported
Domestic Non EuroClosedAny clearing and settlement mechanism or electronic retail payment system (ERPS) approved for domestic interbank transfer within a given EU member's borders. Depending on the country in question. such systems are built on different platforms and based on varying payment products and services to allow firms, individuals, government and other economic agents to transfer money on a daily basis without having to use cash. • IBAN
• BIC
EU domestic payments systems Supported
BankgiroClosedProprietary clearing system (a giro) in Sweden used for transactions such as bill payments. It is owned by Swedish banks. The clearing system is connected with the banks enabling payments to be received directly into bank accounts. • Bankgiro number Sweden Supported
PlusGiroClosedFormerly PostGirot, PlusGiro is a Swedish money transaction system, owned by Nordea. • PlusGiro number Sweden Supported
SWIFTClosedSociety for Worldwide Interbank Financial Telecommunication – provides a secure network allowing more than 10,000 financial institutions in 212 different countries to send and receive information about financial transactions to each other. As broadly used as SWIFT is, keep in mind that it is only a messaging system; SWIFT does not hold any funds or securities, nor does it manage client accounts. • Account number
• BIC
International/cross-border payments Supported

Use Cases: Which payment system to use

Some objects and fields in a payment request are common to all banks. Others are bank-dependent, like the payment system(s) 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 A2AClosedAccount-to-Account – payments that move money directly from one account to another without the need for additional intermediaries or payment instruments, such as cards. payment initiation: domestic payments and cross-border 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, FPSClosedFaster Payments Service – UK banking initiative to reduce payment times between different banks' customer accounts from the three working days that transfers take using the long-established BACS system to typically a few seconds., CHAPSClosedClearing House Automated Payments System – used by large financial institutions that need to transfer billions of dollars worth of currency each day. To assist in these transfers, CHAPS enables real-time fund transfers and can accommodate frequent large transfers with virtually no delay. The speed of CHAPS also substantially eliminates the risk that senders will cancel their transfers before they are accepted by the recipient. CHAPS is administered by the Bank of England (BoE) and is used by 30 participating financial institutions. Approximately 5,500 additional institutions also engage with the system by way of partnership agreements with the 30 primary members., and BACSClosedBankers Automated Clearing Services – an electronic payment made directly from one UK bank account to another, taking up to three working days to arrive. There are two main types of Bacs payment - Direct Credit, which is a bank transfer, and Direct Debit, where one party automatically takes payment from another party’s account with their authorisation. are domestic payment systems in the UK, as seen in the Beneficiary Accounts table above. SORBNETClosedPoland's national RTGS system for high-value and urgent domestic payments. RTGS stands for real-time gross settlement, a continuous process of settling payments on an individual order basis without netting debits with credits across the books of a central bank (i.e., transaction bundling). SORBNET is owned and operated by the National Bank of Poland (NBP). It has 50 direct participants. and ElixirClosedA payments system that ensures electronic interbank settlement in Poland. Transactions directed to the system are settled within one of three Elixir sessions held each business day and closed on the same day in the National Bank of Poland's SORBNET2 system, which guarantees interbank transfer of funds. are domestic payment systems in Poland; BankgiroClosedProprietary clearing system (a giro) in Sweden used for transactions such as bill payments. It is owned by Swedish banks. The clearing system is connected with the banks enabling payments to be received directly into bank accounts. and PlusgiroClosedFormerly PostGirot, PlusGiro is a Swedish money transaction system, owned by Nordea. are the domestic payment systems in Sweden; and so forth.

Cross-border payments happen when the payee and the recipient are in different countries. However, with the advent of the single euro payments marketClosedMarket comprising the 28 EU member states toether with the four members of the European Free Trade Association (Iceland, Liechtenstein, Norway, and Switzerland). Monaco and San Marino are also part of SEPA., SEPAClosedSingle Euro Payments Area – a payments system created by the European Union (EU) which harmonizes the way cashless payments transact between euro countries. European consumers, businesses, and government agents who make payments by direct debit, instant credit transfer, and through credit transfers use the SEPA architecture. The single euro payment area is approved and regulated by the European Commission. SEPA currently includes 36 members. It encompasses the 28 EU member states along with Iceland, Norway, Liechtenstein, Switzerland, Andorra, Vatican City, Monaco and San Marino. The single euro payment area remains an ongoing, collaborative process between these parties. SEPA is in the process of harmonizing rules regarding mobile and online payments. 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. All other cross-border transfers must use SWIFTClosedSociety for Worldwide Interbank Financial Telecommunication – provides a secure network allowing more than 10,000 financial institutions in 212 different countries to send and receive information about financial transactions to each other. As broadly used as SWIFT is, keep in mind that it is only a messaging system; SWIFT does not hold any funds or securities, nor does it manage client accounts..

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 modelled based on these examples.

Send EUR from EU to UK

This entails a cross-border interbank transfer in which the payer's bank is located in an EU member country and the payee's bank is in the UK. We will assume that the bank has already been selected by the user and the currency is EUR.

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 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 description of the payment – an identifier that will be used for reconciliation when funds are cleared within beneficiary’s account
  • a redirect URLClosedUniform Resource Locator (aka web address) – specifies a location on a computer network and a mechanism for retrieving it. – 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 under Bank Selection for details.

You can provide more information for traceability and reconciliation in accordance with your business practices (see Swagger Object and Field Definitions 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 — CMA9ClosedAs part of the Open Banking initiative, the CMA9 are the nine largest banks in the UK as determined by the Competition and Markets Authority (CMA). The CMA is an independent department of the UK government chartered to promote market competition and fairness, and reduce any harmful monopolies., NextGenPSD2ClosedCommon API standard for PSD2 developed by the Berlin Group to create uniform and interoperable communications between banks and TPPs., PolishAPIClosedOpen Banking API standard adopted by banks in Poland to enable TPP access to payment accounts in accordance with PSD2 rules and regulations., or STETClosedCreated according to the new Payment Services Directive (PSD2), this API aims to provide a secure and easy-to-use set of services to be implemented by European ASPSPs. — and typically contain debtor/creditor identifiers and regulatory reporting codes for international payments.

The payment rail (transfer method) can be SEPAClosedSingle Euro Payments Area – a payments system created by the European Union (EU) which harmonizes the way cashless payments transact between euro countries. European consumers, businesses, and government agents who make payments by direct debit, instant credit transfer, and through credit transfers use the SEPA architecture. The single euro payment area is approved and regulated by the European Commission. SEPA currently includes 36 members. It encompasses the 28 EU member states along with Iceland, Norway, Liechtenstein, Switzerland, Andorra, Vatican City, Monaco and San Marino. The single euro payment area remains an ongoing, collaborative process between these parties. SEPA is in the process of harmonizing rules regarding mobile and online payments., which requires the payee's IBANClosedInternational Bank Account Number – a number attached to all bank accounts in the EU countries, plus Norway, Switzerland, Liechtenstein and Hungary. The IBAN is made up of a code identifying the country to which the account belongs, the account holder's bank, and the account number itself. and a BICClosedBank Identifier Code – a unique identifier for a specific financial institution. A BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code..

Given the preceding assumptions, here's the minimally required token request payload we'll need to construct:

{

    "requestPayload":

        "refId": "xyztyuberty", // 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": {

                         "account": "GB29 NWBK 6016 1331 9268 19", // payee's IBAN

                         "bic": "LOYDGB2LXXX"// payee's BIC/SWIFT code

                     }

                }

            }

        },

        "description": "Airfare to EU",

        "redirectUrl": "https://sample-merchant-domain.com/transfer"

    }

}

The response payload from the bank via Token for a successful request will contain a request id that uniquely identifies this transfer request, along with a duplicate of your request payload, confirming its details.

Send EUR from UK to EU

A user in the UK wants to make a payment somewhere in the EU. This is the reverse of the previous use case. In this one, we'll request a cross-border interbank transfer in which the payer's bank is located in the UK and the payee's bank is in an EU member country. Again, we will assume that the bank has already been selected by the user.

If we also apply the other assumptions we made in the previous use case, the request payload will look like this:

{

    "requestPayload":

        "refId": "ytrebuytzyx", // 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": {

                         "account": "FR14 2004 1010 0505 0001 3M02 606", // payee's IBAN

                         "bic": "XYZDDGTYXXX"// payee's BIC/SWIFT code

                     }

                }

            }

        },

        "description": "Airfare to UK",

        "redirectUrl": "https://sample-merchant-domain.com/transfer"

    }

}

The response payload from the bank via Token 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 GBP from UK to EU

In this case, we're making a transfer from the UK to somewhere in the EU. The source currency is GBP. For purposes of this example, we'll assume the destination currency is EUR. If payment is expected in a non-euro currency, that currency should be specified in the transferBody. The bank will handle the FX. Because it's a cross-border payment, the payment rail must be swift.

{

    "requestPayload":

        "refId": "bbbcccxyz", // TPP-generated reference ID

        "to": {

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"// Member ID of the TPP initiating the request

        },

        "transferBody": {

            "currency": "GBP",

            "lifetimeAmount": "428.21",

            "transferInstructions": {

                "transferDestinations": {

                     "swift": {

                         "account": "FR14 2004 1010 0505 0001 3M02 606", // payee's IBAN

                         "bic": "XYZDDGTYXXX"// payee's BIC/SWIFT code

                     }

                }

            }

        },

        "description": "Online purchase",

        "redirectUrl": "https://sample-merchant-domain.com/transfer"

    }

}

Once again, the response payload from the bank via Token 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 InstantClosedEuro credit transfers with the funds made available on the account in less than ten seconds at any time and in an area that will progressively span over 27 EU countries and an additional 17 non-EU countries, autonomous regions and territories. (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:

{

    "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

                         "bic": "XYZDDGTYXXX"// payee's BIC/SWIFT code

                     }

                }

            }

        },

        "description": "Online purchase",

        "redirectUrl": "https://sample-merchant-domain.com/transfer"

    }

}

As in the previous examples, the response payload from the bank via Token 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 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 PaymentsClosedUK banking initiative to reduce payment times between different banks' customer accounts down to a few seconds from the three working days transfer time imposed under the BACS system. (fasterPayments). If it's not especially urgent, you can use BACSClosedBankers Automated Clearing Services – an electronic payment made directly from one UK bank account to another, taking up to three working days to arrive. There are two main types of Bacs payment - Direct Credit, which is a bank transfer, and Direct Debit, where one party automatically takes payment from another party’s account with their authorisation. (bacs), which can take up to three working days before the transfer is received. However, if this an especially large transfer needing to occur on the same day and CHAPSClosedClearing House Automated Payments System – used by large financial institutions that need to transfer billions of dollars worth of currency each day. To assist in these transfers, CHAPS enables real-time fund transfers and can accommodate frequent large transfers with virtually no delay. The speed of CHAPS also substantially eliminates the risk that senders will cancel their transfers before they are accepted by the recipient. CHAPS is administered by the Bank of England (BoE) and is used by 30 participating financial institutions. Approximately 5,500 additional institutions also engage with the system by way of partnership agreements with the 30 primary members. is supported by both banks, then chaps is the method to use. For purposes of this example, we will assume a reasonable online purchase amount requiring a funds transfer ASAP, so our payment method will be fasterPayments.

{

    "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/SWIFT 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 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.

Whitelisting Beneficiary Accounts

The transfer destinations you designate in your PIS calls must first be manually added to the dashboard. These are typically TPP-controlled accounts administered for appropriate funds distribution according to the governing regulations where the TPP is licensed. In all cases, for proper payment request initiation, execution, and funds transfer to the correct beneficiary account(s), take the following steps:

  1. Sign in to the Developer Dashboard and select Beneficiary under Settings.
    The List of Accounts is displayed; initially, your list will be empty until you make some entries. Regardless, here you can Add, Modify and Delete accounts.
  2. Add an account by clicking the Add button, then enter the required information: Account Name, Currency, Country, Account Type, and IBAN. BIC is optional.
  3. Click Save to add the information.

Once saved, beneficiary accounts in the list are available as transfer destinations for the payments you initiate by specifying the Account Number/IBAN and optional BIC, as appropriate.

Source Account Validation

The requirement to specify the source account for a transfer is bank-dependent, based on the API standard adopted by the bank and whether the bank supports 1-step or 2-step payment. When required, the instructions.source object specifies the user's bank account from which the payment amount is being debited, and it is set using an accountIdentifier object, which allows the following types of identifiers:

In EU countries that don't use the euro as their domestic currency, iban should be used for domestic source accounts, with the exception of Sweden. For Swedish domestic, the accountIdentifier can be either bankgiro or plusgiro. Specify a plusgiroNumber for the plusgiro payment rail. If the payment rail is bankgiro, provide a bankgiroNumber.

In addition to the Token Platform's bankId and the bank's bic (BICClosedBank Identifier Code – a unique identifier for a specific financial institution. A BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code.), the source also contains a customerData object identifying the payer's legalNames and address (see Swagger Object and Field Definitions for complete object-field specifications).

In accordance with the following rules, Token verifies the source in token requests to avoid preventable account identification errors during payment processing:

  1. If a transfer token request has a non-empty source object, it must also have a populated accountIdentifier. Populating customerData.legalNames without identifying the bank account, for example, will throw an InvalidArgument "Missing required field bank_account or account_identifier in source account" error.
  2. If the accountIdentifier object is populated, it must also have an populated identifier type as listed above; otherwise, an InvalidArgument "Missing required field<field name>in source account" error will result. Here, field name depends on the identifier type. For most types — bban, iban, msisdn, bankgiro, and plusgiro — only one field is mandatory. However, gbDomestic requires both accountNumber and sortCode.
  3. The bankAccount cases, when supported by the source bank, that cannot be mapped to an accountIdentifier type and are therefore excluded from the source validation check comprise CUSTOM, BANK, GUEST, SWIFT, ACH, TOKEN_AUTHORIZATION, and SECRET.

Populating the source object is required for one-step payment; optional for two-step payment.