Initiating Payment

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

• Single Immediate Payments
• Future-dated Payments
• Recurring Payments (Standing Orders)

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 PSUPayment 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, SEPASingle 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. SCTSEPA 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.

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 A2AAccount-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, FPSFaster 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., CHAPSClearing 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 BACSBankers 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. SORBNETPoland'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 ElixirA 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; BankgiroProprietary 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 PlusgiroFormerly 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 marketMarket 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., SEPASingle 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 SWIFTSociety 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
• Send EUR from UK to EU
• Send GBP from UK to EU
• Send EUR from EU to EU
• Send GBP from UK to UK

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 URLUniform 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 — CMA9As 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., NextGenPSD2Common API standard for PSD2 developed by the Berlin Group to create uniform and interoperable communications between banks and TPPs., PolishAPIOpen Banking API standard adopted by banks in Poland to enable TPP access to payment accounts in accordance with PSD2 rules and regulations., or STETCreated 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 SEPASingle 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 IBANInternational 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 BICBank 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:

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:

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.

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 InstantEuro 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:

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 PaymentsUK 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 BACSBankers 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 CHAPSClearing 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.

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:

• Token, for linked accounts
• iban – IBANInternational 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.
• bban – BBANBasic Bank Account Number – represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. See https://www.mobilefish.com/services/bban_iban/bban_iban.php for help with BBAN conversion.
• gbDomestic – 8-digit bank account number in the UK;  also requires the sort_code
• bankgiro – identifier for domestic bank accounts in Sweden
• plusgiro – identifier for domestic transaction clearing system in Sweden
• msisdn – mobile station international subscriber director number is basically the user's mobile phone number; used as a unique identity to enable routing of voice and SMS traffic to and from a specific subscription/ device on a wireless/mobile network

In addition to the Token Platform's bankId and the bank's bic (BICBank 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.