Single Immediate Payments
A single immediate payment (SIP) is a payment initiated on behalf of a PSU for immediate execution. Single 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. transfers have a 3:00 pm cutoff time for same day processing. Requests received after this time will be processed the following business day.
Important reminder: Don't forget that, before initiating a request to a Token-connected bank, you'll first need to get the list of banks in the desired country that support the features you need to access. A GET /banks call filters the list of Token-connected banks based on your selection criteria with respect to bank location and bank-supported features. See Bank Selection using GET /banks for more on filtering and selecting Token-connected banks.
Bank-initiated SIP (1-step)
Putting the full sequence into perspective, the diagram pictured next (hover to enlarge) shows the communication flow for
TPP-initiated SIP (2-step)
The sequence diagram pictured next shows the communication flow for a
Heads-up: For payment requests subject to additional credentials in mandatoryFields, see the discussion on mapping mandatory fields in bank selection for the correct field mapping, paying special attention to the differences in authenticating credentials in the respective request flows; i.e., using the Token webapp versus not using the Token webapp.
If the mandatory user credentials you provide are invalid, the status returned will be unauthenticated, and you will need to repeat the redirect to the bank for consent to have your user try again. Conversely, when the status returned is authenticated, it means the bank has accepted the consent and no redirect is required.
Guidance for making the appropriate POST and GET calls, as well as handling Token's responses to these requests is covered next.
Base URLs
See Base URLs.
Headers
Making a Transfer Token Request
To initiate a payment request with the bank, you'll need to be able to identify yourself as the calling
- Member ID – unique value generated by the Developer Dashboard when you signed up.
- Alias – unique email, domain, eIDAS or realmId you provided when you signed up.
A transfer request must include both parameters.
You can obtain the values from the dashboard by following these steps:
- If the dashboard isn't already open in a browser tab, sign in.
- Click Member Information in the navigation panel on the left.
- Click the "eye" icon to the right of each value to reveal it.
- Copy the value you need.
Payment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both. gives consent
{
"requestPayload"
:
"refId"
: "xyz"
,
"to"
: {
"id"
: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"
// required
member ID; mandatory
"realmId"
: "value available from dashboard"
,
}
},
},
"callbackState"
: "%257B%2522"
, // added to callack URL with hash of CSRF token specified by Token
"transferBody"
: {
"currency"
: "EUR"
,
"lifetimeAmount"
: "10"
,
"transferInstructions"
: {
"transferDestinations"
: {
"fasterPayments"
: {
"accountNumber
": "70000005",
"sortCode
": "700001"
},
"customerData"
: {
"legalNames"
: ["Southside", Southside Products, Ltd"] // populating creditor name is mandatory
}
}
}
},
"description"
: "test"
"redirectUrl"
: "https://sample-merchant-domain.com
/transfer"
}
}
Tip: "Available from Dashboard" indicates a value that can be looked up in the Developer Dashboard under Settings > Member Information.
The most important request fields and their corresponding descriptions are listed in the following table.
Field | Description/Subfields | Required/Optional | |||
---|---|---|---|---|---|
refId |
|
Required | |||
to | Identifies the member initiating the request | Required | |||
id | Member ID of the |
Required | |||
alias |
A human-readable proxy for your member identifier that contains your realmId or alias type (DOMAIN, EMAIL, other) and a value string.
A realmId identifies a member created under the realm of a specific bank. See Member Information in Understanding Dashboard Settings to find your member id and alias. |
Optional; soon to be deprecated | |||
transferBody | Specifies the critical details of the transfer payload: currency, lifetimeAmount, and transferDestinations |
Required | |||
currency | ISO 4217 currency code for the transaction | Required | |||
lifetimeAmount |
Amount of the payment/transfer valued in currency.
Precision: Recommended precision is rounding to 4 decimal places (HALF-EVEN |
Required | |||
instructions | Specifies beneficiary account information and any additional transfer instructions. | Required | |||
|
Required | ||||
callbackState |
Developer-specified string allowing state to be persisted between the request and callback phases of the flow; used for the signature in a GET /token-requests/{tokenRequestId}/token-request-result call, in which the signing payload for the signature is a combination of state and tokenId and validates the tokenId against the callbackstate originally sent by the TPP in the request. Note: The value of callbackState is added to the redirect URL and appended to the hash of the CSRF token specified by Token; e.g.: https://{callback-url}?signature=%7B%22memberId%22%3A%22m%3A3rKtsoKaE1QUti3KCWPrcSQYvJj9% |
Optional | |||
description |
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. |
Optional, with the caveats described in the previous column | |||
disableFutureDatedPaymentConversion | Explicitly disables conversion of an auto single immediate payment to a future-dated payment for requests sent during the bank's out-of-operation hours. Default = false, which means always allow auto SIP![]() ![]() |
Optional | |||
redirectUrl |
Defines the |
Required | |||
remittanceReference | Augmenting refId and description, this is TPP-defined additional information pertinent to TPP's payments policies; for instance, 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 | |||
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 | |||
requestOptions |
|
Optional | |||
*Inclusion of some elements may be optional or bank-dependent |
Heads up: Cited in the table within transferInstructions and nested in source is the accountIdentifier object (required):
"source": {
"
": { "gb_domestic
": {
"account_number
": "70000005",
"sort_code
": "700001"
}
}
}
Remember, whatever you specify as the source and transferDestinations in the request will be reflected in the response.
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-DSS
Payment 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, Regex
API 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.
Payee Information
- STET
Created 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.
- CMA9
As 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., NextGenPSD2
Common API standard for PSD2 developed by the Berlin Group to create uniform and interoperable communications between banks and TPPs., and PolishAPI
Open Banking API standard adopted by banks in Poland to enable TPP access to payment accounts in accordance with PSD2 rules and regulations. have the creditor name and account identifiers, as well as the creditor agent
Financial institution servicing an account for the creditor.BIC
Bank 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 or HSBC, the creditor name (creditorAcount.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:
Token | OBIE |
---|---|
flats | SubDepartment |
house_name | Department |
house_number | BuildingNumber |
street | StreetName |
post_code | PostCode |
city | TownName |
district | CountrySubDivision |
country | Country |
These creditor post address fields can be found in Token's protobuffer technical reference.
Making a Gateway Request "on behalf of" – Using the actingAs Property
Resellers and TPPs contractually granted permission by Token can create a token on behalf of another party by configuring the actingAs object in the requestPayload. Here's an example:
: {
"displayName"
: "Rudolfo's Pizzeria"
,
"logoUrl"
: "https://cdn-somewhere-on-the-web.com"
,
"refId"
: "Merchant-No. TX14JG6890"
,
// unique reference for internal tracking and reporting; e.g., a merchant-id
"secondaryName"
: "rudys-restaurants.it"
}
Each identifier is defined in the following table:
Field | Description | Required/ Optional |
---|---|---|
displayName | Name of recipient shown to user | Required* |
logoUrl | URL pointing to recipient's logo | Optional |
secondaryName | Domain or email address of recipient shown to user along with displayName | Optional |
refId | TPP's discretionary reference identification of the recipient, opaque to Token; can be used by a "gateway" business member to (uniquely) define a merchant that is acting through it.The uniqueness of refId should be handled by the gateway member; typically a reseller requiring separate reports for each participating merchant it is representing. | Optional |
* Required when specifying ActingAs, although ActingAs is otherwise optional. |
A "gateway" is a business member empowered to act on behalf of a merchant that is not registered as a member in the Token system. The gateway member must have ACT_ON_BEHALF_OF permission from Token and populate the actingAs field in the token request accordingly to indicate the merchant on whose behalf it is acting.
Processing the Response
Here's an example of the response you'll receive:
"tokenRequest"
: {
"id"
: "rq:3g5RVV7Z4oU9P5rtzX2YhnssuPC5:5zKtXEAq"
, // request-id; add to BASE_URL for consent
"requestPayload"
: {
"to"
: {
"alias"
: {
"type"
: "EMAIL"
,
"value"
: noverify@token.io"
}
"id"
: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"
//
member ID
},
"transferBody"
: {
"currency"
: "EUR",
"lifetimeAmount"
: "10",
"transferInstructions"
: {
"transferDestinations"
: {
"fasterPayments"
: {
"accountNumber
": "70000005",
"sortCode
": "700001"
}
}
}
},
"description"
: "test",
"redirectUrl"
: "https://sample-
merchant-domain.com/transfer"
}
}
Create the redirect URL by appending the request id in the response (shown above in red) to the redirect base URL, then send it to the user to provide explicit consent to the bank.
https://{{BASE_URL}}/app/request-token
/{{Insert request-id here
}}
// example = https://web-app.sandbox.token.io/app/request-token/rq:3RKfCA7KQEEZERLoFsAt3MoAnoP5:5zKtXEAq
Tip: You can specify a particular language by passing its language code (lang=country-code) as a query parameter, appended to the URL above, which the user can override in the webapp according to personal preference. Here's an example for passing the desired ISO 639-1Codes for the representation of names of languages—Part 1: Alpha-2 code, is the first part of the ISO 639 series of international standards for language codes. Part 1 covers the registration of two-letter codes. There are 184 two-letter codes registered as of December 2018. The registered codes cover the world's major languages.
See https://www.iso.org/iso-639-language-codes.html language code for German (de):
https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?
TPPs using Token's licence only: This webapp URLUniform Resource Locator (aka web address) – specifies a location on a computer network and a mechanism for retrieving it. redirects the PSU to the Token Web App, which displays a payment confirmation page (pictured, hover to enlarge):
Note: If you did not capture the source account number from the PSU in your UI after user bank selection (see Filtering Banks), the user is presented with an input field (shown in the payment confirmation page above) in which to enter the source account number (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.).
Upon user consent, Token will redirect the user back to the
"redirectUrl": "https://sample-merchant-domain.com"
/pis?tokenId=sample_token_id
"redirectUrl": "https://sample-
merchant-domain.com"
/pis?transferId=sample_transfer_id
To derive the complete redirect URL, you'll need to URL decodeURL encoding makes sure that the characters in the URL that are not allowed to be put into the URL directly can still be used. For example a space or : is not allowed, but replacing it with %20 or %3A encodes a space or : (and most browsers will display a space in the browser bar).
For encoded URLs, use Java's URLDecoder (java.net.URLDecoder) unless you have a different preference. the tokenId
Using the tokenId sent by the bank, which confirms PSU consent, you can now initiate payment.
If the bank supports one-step payments, the callback will contain a transferId and a transferStatus (see Payment Status: Value and Meaning for the list of possible status codes), which you can then display to the customer/user. Use the transferId, as necessary, to check for status updates with a GET /transfers/{transferId} call, presuming you didn't subscribe to a webhook in the original token request. See Fetching the Status of a Payment below for more on this.
For two-step payments, you'll need to redeem the transfer token with a POST /transfers request containing the Token-provided tokenId. Here's an example:
{
"payload"
: {
"refId"
: "{{your reference identifier}}", // optional
"tokenId"
: "{{TOKEN_ID}}"
, // tokenId in redirectUrl
"amount"
: {
"value"
: "100",
"currency"
: "EUR"
}
}
}
The most important request fields and their corresponding descriptions are listed in the following table.
Field | Description/Subfields | Required/Optional | ||
---|---|---|---|---|
payload | refId | Warning: If the description in subsequent token lookups/changes/updates (retrieve, redeem, or cancel) doesn't match the description in the originating token request, an exception will be thrown. |
Required | |
tokenId | Bank-generated identifier returned in the response to the original payment request | Required | ||
amount | value |
Amount of the payment/transfer valued in currency.
Precision: Recommended precision is rounding to 4 decimal places (HALF-EVEN |
Required | |
currency | ISO 4217 currency code for the transaction | Required | ||
payloadSignature | memberId | Member ID of the |
Required* | |
keyId | Your certificate's public key identifier | Required* | ||
signature | Cryptographic signature guaranteeing the authenticity of the payload. | Required* | ||
* Not required if you are using an API key |
You'll receive a transferId and transferStatus in a callback, which you can then display to the customer/user.
Please refer to the API's Swagger Object and Field Definitions and Swagger Specification for additional details on all of the above.