Single Immediate Payments
A single immediate payment is the most basic transfer type. It involves a single transfer made to one or more specified account destinations immediately upon customer authentication and authorisation. Transfer token requests for other supported payment types — future-dated, standing order, and bulk transfer — all follow the same basic structure as a single immediate payment, but with the addition of important scheduling parameters that determine when payment is made and to whom.
All transfer token requests, regardless of the Token SDK chosen, are created with the selected-language variant of the transferTokenRequestBuilder() method. Once the token request is created, you store it, awaiting a corresponding request-id, which is returned by the bank via Token in a response payload. In addition to the request-id, the response payload reflects all the information you included in your original request. Now equipped with the request-id, you can set your transfer destination(s)i, f you omit it in the originating token request, and redeem the token, thereby transferring the specified payment amount from the payer's bank account to the payee's bank account.
For single immediate payments, you set the transfer destination, create the request and store it. Here's an example:
* Creates and stores a transfer token request.
* @param payee Payee Token member (member requesting transfer token creation)
* @return a token request id
public static String storeTransferTokenRequest(Member
// build the transfer token request for single immediate payment
// first, set the transfer destination
sepaDestination = TransferDestination.
"DE89 3704 0044 0532 0130 00")
// then build the request
request = TokenRequest.
// member ID of payee
// member alias of payee
// description of payment/transfer
// add transfer destination
// payer's alias
// validates the session ID
// use keys in bank authorization metadata from getBanks() response
// now store the token request
|actingAs||Party or entity for which the to member is acting as a proxy. See Creating a Token on Behalf of another Party for details on setting the properties for this field.||Optional|
Payment value calculated in currency.
Precision: Recommended precision is rounding to 4 decimal places (HALF-EVENRound-half-even algorithm, often referred to as Banker's Rounding because it is commonly used in financial calculations. Half-way values are rounded toward the nearest even number. Thus, 3.5 will round up to 4 and 4.5 will round down to 4.), although the TPP can set its own desired precision. However, be aware that certain banks may handle rounding differently — some with greater precision (i.e., more decimal places), others with reduced rounding precision (fewer decimal places). The Token Platform strictly serves as the pipeline between the TPP and the bank, imposing no precision restrictions.
|authorizationMetadata||Needed to capture additional information from the user for initial authorization by the bank, thereby allowing the user to proceed with providing consent for the initiation request. Maps the key-value pairs from the getBanks() response, where key is the name of the field and value is the value of the field.||Required|
|bankId||When specified, indicates you wish to bypass the Token bank selection UI and use your own bank selection UI for the request. See Using the getbanks Method.||Optional|
|callBackState||TPP-specified string that persists state between request and callback.||Optional, but recommended|
|currency||ISO 4217 alpha-3 currency code.||Required|
|customizationId||Identifier for customizing the UI of the Token web app (see Customising the Token Webapp for details).||Optional|
Description of the payment with the following qualifiers:
This description field maps to description in the bank's consentRequest presented to the user.
Warning: If description in a subsequent token request for lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception will be thrown.
|from||member_id or alias of the user; if included, indicates you wish to bypass the Token user email entry UI. See Specifying User Email Address.||Optional|
|member||The customer/user; payer of the token.||Required|
|receiptRequested||Boolean; requests a receipt be sent to the from member's default email address.||Optional|
|redirectUrl||Specifies the callback URL where your server will initiate token redemption.||Required|
|reference||Augmenting refId and description, this is TPP-defined additional information pertinent to TPP's payments policies; for instance, could contain a full or partial credit card number when payment is being initiated for a credit card payment. Securely hashed to safeguard its transmission throughout the communication flow, this field should be considered by TPPs wishing to augment their transaction reference data for tracking and audit control.||Optional|
Reference identifier for the token; not to be confused with requestId. RefId is typically used by the TPP to reconcile transactions against payments received. RefId maps to tppRefId in the bank's consentRequest. It is needed to match/verify the originating token request with the bank's consent request.
Warning: A description mismatch between the originating token request and subsequent token lookups/changes/updates (retrieve, redeem, or cancel) will throw an exception.
|sourceAccountId||Account number from which the amount is being debited; set using the AccountIdentifier object, which allows four types of account identifiers:
Although setting source with the BankAccount object has been deprecated, it is still supported
|to||member_id and alias of the transfer recipient||Required|
|token_expiration||Sets the expiration date and time for the token request (default is 20 minutes); override of default value is not supported by all banks.||Optional|
|traceID||TPP-provided unique value captured by Token and sent across to the bank to be stored with the request throughout its lifecycle as an audit-trail aid.||Optional|
|transferDestinations||Payment beneficiary bank account(s); where payment will be sent. Typically an 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. for 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., or SORT codeNumber 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”. and Account Number(s) for 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.. See Beneficiary Account Details for supported instruments.||Required|
|userRefId||Identifier that can be used to track a user member claimed by the TPP.||Optional|
Caution: A PANPrimary Account Number – refers to a 14-, 15-, 16-, or even up to 19-digit number generated as a unique identifier designated for a primary account; also called payment card number and permanent card number. is disallowed in the token request payload within the refId and description fields. In accordance with the PA-DSSPayment Application Data Security Standard – Council-managed program formerly under the supervision of the Visa Inc. program known as the Payment Application Best Practices (PABP). The goal of PA-DSS is to help software vendors and others develop secure payment applications that do not store prohibited data, such as full magnetic stripe, CVV2 or PIN data, and ensure their payment applications support compliance with the PCI DSS. Payment applications that are sold, distributed or licensed to third parties are subject to the PA-DSS requirements. In-house payment applications developed by merchants or service providers that are not sold to a third party are not subject to the PA-DSS requirements, but must still be secured in accordance with the PCI DSS. security standard, RegexAPI to define a pattern for searching or manipulating strings. is used for pattern matching of numeric strings that intentionally or inadvertently reveal or resemble a PAN in the refId or description of a token request. Potential PAN patterns found will now throw an exception.
Remember, whatever you specify as the transferDestination in the request will be reflected in the response. This means accuracy is extremely important here.
- 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. requires creditor account information.
- 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., and PolishAPIThe PolishAPI standard is the key part of the Open Banking on the Polish financial market. It is defining the interface enabling third parties to access payment accounts, based on amended directive on payment services in the internal market (PSD2). have the creditor name and account identifiers, as well as the creditor agentFinancial institution servicing an account for the creditor.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.. However, these are optional fields, so the presence of creditor account information is bank-dependent.
- CMA9 needs the creditor agent address, whilst PolishAPI requires the creditor's address.
If you are initiating a payment to Barclays Bank UK, the creditor name can be no more than 18 characters. If this limit is exceeded, the bank will reject the payment.
Otherwise, when providing creditor name and address for CMA9 international payments, bear in mind that certain banks, such as HSBC, require creditor information to process international payments, despite its designation as "optional" in the OBIE specification. To be safe with respect to CMA9 international payments, provide this information in the customerData fields of the transferDestination object. The OBIEOpen Banking Implementation Entity – organization created by the CMA (Competition and Markets Authority) to deiver APIs, data structures and security architectures that enable developers to harness technology, making it easy and safe for account holder's to share their financial information held by the banks with third parties. information maps to its Token counterpart as follows:
These creditor post address fields can be found in Token's protobuffer technical reference.
Certain banks, such as HSBC, require creditor information to process international payments, despite its designation as "optional" in the OBIE specification. To be safe with respect to CMA9 international payments, provide this information in the customerData fields of the transferDestinations object, wherein the OBIEOpen Banking Implementation Entity – organization created by the CMA (Competition and Markets Authority) to deiver APIs, data structures and security architectures that enable developers to harness technology, making it easy and safe for account holder's to share their financial information held by the banks with third parties. information maps to its Token counterpart as follows:
These creditor post address fields can be found in Token's protobuffer technical reference.
You can store the created request without a transfer destination and, instead, specify a transferDestinationsCallback URL for Token to call upon customer authentication and authorisation. Or, you can specify the destination when you redeem the token. Additional details can be found in Setting Transfer Destinations.