Future-dated Payments

Future dating is the scheduling of a banking transaction to occur at a later date. An authorized future-dated payment (FDP) is an agreement stipulating that funds will not be transferred and made available to the recipient until a specified point in the future.

Individual consumers and companies use future dating to control cash flow by scheduling payments to occur when sufficient funds are present in the paying account. Future dating a payment involves giving the user's bank instructions to send the payment on a specific date in the future, either the next day or beyond. In most cases, one-time future-dated and future recurring transfers scheduled for a weekend or a non-business day are processed on the next business day. All other future-dated transfers are processed at the end of the business day requested. The cut-off time and delivery date of external transfers are subject to each bank's account terms and conditions for the type of account specified.

Bank-initiated FDP (1-step)

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

TPP-initiated FDP (2-step)

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

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

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

Environment BASE_URL
API calls
Production https://api.token.io
Sandbox https://api.sandbox.token.io
Web App Redirect (for consent)
Production https://web-app.token.io
Sandbox https://web-app.sandbox.token.io

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 or domain you proveided 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.

Some banks in Germany, Austria and Hungary require the TPP to capture additional authentication information upfront from the user before a redirect to the bank.

If the selected bank imposes this initial credentials check requirement, you'll need to capture the credentialFields specified by the bank (e.g., the user'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.) in its response to your GET /banks call (see Bank Selection using GET /banks) and include this information in your payment request.

In addition, when initial credentials are required by the user-selected bank, the redirect URL in the sandbox will be:

https://tpp-integration.sandbox.token.io/initiatePayment/callback?redirect-url={{your-redirect-url}}

For production, the redirect URL changes to:

https://tpp-integration.token.io/initiatePayment/callback?redirect-url={{your-redirect-url}}

Here, {{your-redirect-url}} is your standard TPP redirect URL.

The exchange iterations necessary to provide initial credential information to the bank take place in the background.

See also Mandatory Token Request Pass-ins and Authorisation Models in Bank Selection using GET /banks for information about providing required bank-specific information in your request. Please note that bank-specified MandatoryFields may be different for different banks.

If you are not connecting to a bank in Germany, Austria or Hungary, the requirement for an initial credentials check using the redirect URL format above does not apply and you should instead use the standard format outlined below.

Once the PSUClosedPayment 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 with a requestPayload:

{

    "requestPayload": {

        "refId": "xyz",

        "to": {

            "alias": { // include only one type and its corresponding value

                "realmId": "value available from dashboard",

                "type": "EIDAS",

                "type": "EMAIL",

                "value": "noverify@token.io" // example value

                "value": "value available from dashboard"

            }

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"// TPP member ID

        },

        "authorizationMetadata": {   // map from response to GET /banks call

            "additionalProp1": "string",

            "additionalProp2": "string",

            "additionalProp3": "string"

        },

        "transferBody": {

            "currency": "EUR",

            "lifetimeAmount": "10",

            "instructions": {

                "transferDestinations": [

                    {

                         "sepa": {

                             "iban": "testIBAN",

                             "bic": "testBIC"

                         }

                    },

                ]

                "executionDate": "2021-10-14T07:22Z"

            }

        },

        "description": "test",

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

    }

}

The most important request fields and their corresponding descriptions are listed in the following table.

Key Fields in the Transfer Token Request for SIP
Field Description/Subfields Required/Optional
refId  TPP-generated 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: 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
to Identifies the member initiating the request 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.

Required
id Member ID of the TPP, a constant value in all requests; see Member Information in Understanding Dashboard Settings. Required
authorizationMetadata Maps the key-value pairs from the GET /banksresponse, where key is the name of the field and value is the value of the field. 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. Required*
transferBody Specifies the critical details of the transfer: currency, lifetimeAmount, and transferDestinations(beneficiary account information). Required
currency Currency for the transaction Required
lifetimeAmount Amount of the payment/transfer valued in currency.

Precision: Recommended precision is rounding to 4 decimal places (HALF-EVENClosedRound-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 it's 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.

Required
instructions Specifies beneficiary account information and any additional transfer instructions. Required
transferDestinations These are the beneficiary account details that determine if the request is for a domestic, 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., or cross-border payment. Generally, the beneficiary is the TPP. See Whitelisting Beneficiary Accounts for guidance on adding, modifying, and deleting accounts.

A creditor name (customerData.legalNames) for the destination account is a required parameter: transferInstructions.transferDestinations.customerData.legalNames

executionDate Date in the future on which transaction will be made.
 
callbackState Developer-specified string allowing state to be persisted between the request and callback phases of the flow Optional
description Description of the payment with the following qualifiers:
  • description in a subsequent call must match description in originating request
  • description omitted in originating request must also be omitted in subsequent calls
  • description omitted in subsequent call will be replaced with refId

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
redirectUrl Defines the bank's callback URL where your server initiates token redemption.

Important: When initial credentials are required by the bank as specified in its GET /banks response, see the note above for more on how to construct the redirect URL.

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
requestOptions • Bank ID where payment is to be initiated
• Receipt Requested – to specify that an email
  receipt is to be sent to the PSU by Token
Optional
source 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

  • Required for one-step payment
  • Optional for two-step payment
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
*Inclusion of some elements may be optional or bank-dependent

Caution: A PANClosedPrimary 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-DSSClosedPayment 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, RegexClosedAPI 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 a transferDestination in the request will be reflected in the response. This means accuracy is extremely important here.

Payee Information

Submission and return of payee information is not supported by all banks. When supported, and based on the standard adopted by the bank, creditor account (payee) information (legal name and/or address) is included in customerData within providerTransactionDetails for single transactions. When included in the request, payee/creditor account information is available in the response, regardless of the API standard adopted by the bank; typically, however, the following guidelines apply:

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.

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"// TPP member ID

        },

         "transferBody": {

            "currency": "EUR",

            "lifetimeAmount": "10",

            "instructions": {

                "transferDestinations": [

                    {

                         "sepa": {

                             "iban": "testIBAN",

                             "bic": "testBIC"

                         }

                    }

                ]

                "executionDate": "2021-10-14T07:22Z"

            }

        },

        "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 bank.

https://{{BASE_URL}}/app/request-token/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-1ClosedCodes 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 (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.).

Upon user consent, Token will redirect the user back to the TPP with either a tokenIdor atransferId as a query parameter, depending on the bank's support for two- or one-step payments, respectively.

"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 decodeClosedURL 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.

For bank-initiated (1-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.

For TPP-initiated (2-step) payments, you'll 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": "10",

         "currency": "EUR"

     }

 },

 "payloadSignature": {

     "memberId": "m:ifnUakCEJAot1XSXsmrMZHHd19A:5zKtXEAq",

     "keyId": "0NgHZ8jUKdyHRJFW",

     "signature": "D4iVAPUboFhKE8pQYZjwfH05TxRDSqgYZO94DgUHfx4lGddlZkIooKo6M5AVE"

 }

}

The most important request fields and their corresponding descriptions are listed in the following table.

Field Description/Subfields Required/Optional
payload refId  TPP-generated 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: 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-EVENClosedRound-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 it's 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.

Required
currency ISO 4217 currency code for the transaction Required
payloadSignature memberId Member ID of the TPP, a constant value in all requests; see Member Information in Understanding Dashboard Settings. 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 the transferStatus in a callback, which you can then display to the customer/user. See Payment Status: Value an Meaning for the list of possible status codes.

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.