Single Immediate Payments

A single immediate payment (SIP) is a payment initiated on behalf of a PSU for immediate execution. There are, however, certain restrictions imposed by the various payment systems. For instance, 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. transfers have a 3:00 pm cutoff time for same day processing. Requests received after this time will be processed the following business day. It's also important to note that, as a general rule, sending euros outside the UK using SEPA can take up to 2 business days before being credited to the beneficiary bank, although in most cases the money arrives in the beneficiary's bank account on the next business day.

Auth AND Transfer Payment Initiation – SIP

Putting the full sequence into perspective, the diagram pictured next (hover to enlarge) shows the communication flow for a bank-initiated single immediate payment.

Auth PLUS Transfer Payment Initiation — SIP

The sequence diagram pictured next shows the communication flow for a TPP-initiated single immediate payment.

Guidance for making the appropriate POST and GET calls, as well as handling Token's responses to these requests is covered next.

Detailed API request-reply code samples supporting each use case are available in the API's Postman profiles. Download the PostmanA tool for performing integration testing with your API. It allows for repeatable, reliable tests that can be automated and used in a variety of environments and includes useful tools for persisting data and simulating how a user might actually be interacting with the system. app from https://www.postman.com/downloads/.

Base URLs

Correlated in the following table, the {{BASE_URL}} for calls and redirects depends on the environment in which you're operating.

Be sure to include the BASE_URL for the appropriate environment and purpose in each call.

Making the Token Request

To initiate a payment request with the bank, you'll need to be able to identify yourself as the calling TPP using your Member ID and your Alias, defined as follows:

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

    (1)   If the dashboard isn't already open in a browser tab, sign in.

    (2)   Click Member Information in navigation panel on the left.

    (3)  Click the "eye" icon to the right of each value to reveal it.

    (4)   Copy the value you need.

Once the PSUPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both. gives consent for you to initiate PIS on the PSU's behalf, here's the call for POSTing /token-requests):

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.

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.

Here's an example of the response you'll receive:

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.

Tip: You can specify a particular language by passing its language code (lang=country-code) as a 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?lang=de

TPPs using Token's licence only: This 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 TPP with either a tokenId or a transferId as a query parameter, depending on the bank's support for two- or one-step payments, respectively.

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 or transferId value provided.

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.

You'll receive a transferId and transferStatus in a callback, which you can then display to the customer/user.

Important: The POST /transfers call must pass in an appropriate authorisation header containing your authentication key. See Construct the Request Authorisation Header in Onboarding to review the details.

To get information about a specific token, use a GET /tokens/{tokenId} call. To subsequently retrieve information about a specific payment, use a GET /transfers/{transferId} call.

Please refer to the API's Swagger Reference for additional details on all of the above.