Standing Orders / Recurring Payments

A standing order (or a standing instruction) is an instruction to pay a set amount at regular intervals to a beneficiary account. The instruction is sometimes known as a banker's order. These transactions are also referred to as recurring payments — giving permission to a retailer or merchant to deduct payments for goods or services from the PSU's bank account on a regularly scheduled basis. In addition to the information required for a single payment, standing orders need a start date, an end date, and a frequency.

The frequencies supported for standing orders comprise daily (DAIL), weekly (WEEK), twice-weekly (TOWK), monthly (MNTH), twice-monthly (TOMN), quarterly (QUTR), semiannually (SEMI), and yearly (YEAR). Hence, if a customer wishes to authorise a standing order beginning on a startDate of 2020-08-01 and lasting until an endDate of 2022-07-31, with a frequency of MNTH, this represents 24 equal monthly payments to be executed on the first of each month or the next business day after, beginning in August of 2020 and ending July 2022.

The Token API also supports the CMA9 specification for variable installment payment amounts and dates (first, recurring, and last).

Auth AND Transfer Standing Order Submission

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

Auth PLUS Transfer Standing Order Submission

The sequence diagram pictured next shows the communication flow for a TPP-initiated SIP.

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

CMA9 Standing Orders: As mentioned above, the SDK also supports the more granular frequency settings for standing orders required by the CMA9ClosedAs 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. specification, in addition to supporting variable payment amounts (first, recurring, last). Optional CMA9-specific parameters are labeled as such in the list of key fields.

To test CMA9v3 standing orders, please use Ozone Bank.

Detailed API request-reply code samples supporting each use case are available in the API's Postman profiles. Download the PostmanClosedA 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/.

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 IDand 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 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):

{

    "requestPayload": {

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

        },

        "standingOrderBody": {

                "instructions": {

                    "metadata": {

                    },

                    "transferDestinations": [{

                        "sepa": {

                            "bic": "123456",

                            "iban": "IT12345678"

                        },

                        "customerData": {

                            "legalNames": ["Southside"]

                        }

                    }]

                },

                "startDate": "2019-12-16",

                "endDate": "2019-12-20",

                "frequency": "DAIL",

                "amount": "7.96",

                "currency": "EUR"

        },

        "description": "test",

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

    }

    "requestOptions": {

        "from": {

        }

    }

}

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

Key Fields in the Transfer Token Request for Standing Order
Field Required/Optional Description
alias Required A human-readable proxy for your member identifier that contains your alias type (DOMAIN, EMAIL, other) and a value string. Find your alias in the sandbox after logging in by clicking the Construct Payload button in the Payload Builder card.
authorizationMetadata Required Maps the key-value pairs from the GET /banks response, 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.
callbackState Optional Developer-specified string allowing state to be persisted between the request and callback phases of the flow
currency Required ISO 4217 alpha-3 currency code.
description Optional, with the caveats described in the next column 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.

endDate Optional Specifies the end date for completing the order in ISO 8601 format (YYYY-MM-DD or YYYYMMDD).

For non CMA9-specific standing orders involving a CMA9 bank, endDate maps to finalPaymentDateTime, consistent with the OBIE standard.
finalPayment Required

CMA9-specific standing orders only. Last and final payment valued in currency in accordance with the OBIE standard. Value can be a different amount with respect to firstPayment and nextPayment.

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.

finalPaymentDateTime Required* CMA9-specific standing orders only. Scheduled date and time for finalPayment in accordance with the OBIE standard. Required if numberOfPayments is not specified.
firstPayment Required CMA9-specific standing orders only. First or "down" payment valued in currency in accordance with the OBIE standard. Value can be a different amount with respect to nextPayment and finalPayment.

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.

firstPaymentDateTime Required CMA9-specific standing orders only. Scheduled date and time for firstPayment in accordance with the OBIE standard.
frequency Required ISO 20022 code for the scheduled frequency of standing order payments:

    • DAIL – daily; once a day
    • WEEK – weekly; once a week
    • TOWK – twice weekly; two times a week
    • MNTH – monthly; once a month
    • TOMN – twice monthly; two times a month
    • QUTR – quarterly; once every 3 months
    • SEMI – semi-annually; two times each year
    • YEAR – annually; once a year

Note: The day of the week for each installment will be based on the day of week for startDate (e.g., if startDate falls on a Wednesday, every subsequent payment will also occur on a Wednesday). However, if frequency is MNTH, the day of the month for startDate is used (e.g., if startDate is the 5th of the month, all monthly installments will occur on the 5th day of each succeeding month), unless startDate is the last day of the month. If so, all subsequent monthly installments will occur on the last day of each month.
id Required Member ID of the TPP, a constant value in all requests; find yours in the sandbox after logging in by clicking the Construct Payload button in the Payload Builder card.
lifetimeAmount Required Payment amount valued in currency. For recurring payments (standing orders), this is the payment value per scheduled transfer.

For standing orders involving standard (non-variable) payments from a CMA9 bank, lifetimeAmount maps to firstPayment, consistent with the OBIEClosedOpen 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. standard.

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.

nextPayment Required CMA9-specific standing orders only. Recurring installment payment amount scheduled by nextPaymentDateTime and frequency in accordance with the OBIE standard.
nextPaymentDateTime Required CMA9-specific standing orders only. CMA9 recurring payment date and time for installments scheduled between firstPaymentDateTime and finalPaymentDateTime in accordance with the OBIE standard.
number_of_payments Required* CMA9-specific standing orders only. int32 field specifying the total number of payments in accordance with the OBIE standard. Required if finalPaymentDateTime is not specified.
payment_amount Optional CMA9-specific standing orders only. CMA9 recurring payment amount for scheduled installments between startDate and endDate in accordance with the OBIEClosedOpen 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. standard.
payment_date_time Optional CMA9-specific standing orders only. CMA9 recurring payment date and time for installments scheduled between startDate and endDate in accordance with the OBIE standard. If not specified for CMA9 orders, scheduled installments will default in accordance to the day/date ascribed to frequency (see the note above).
redirectUrl Required Defines the callback URL where your server initiates token redemption
reference Optional 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.
refId Optional

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.

remittanceInformation Optional CMA9-specfic standing orders only. Creditor reference or payment remit identification for end-to-end transaction identification in accordance with the OBIE standard.
requestOptions Optional • 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
source • Required for one-step payment
• Optional for two-step payment
Debtor account number – account number from which the amount is being debited
startDate Required Date on which the standing order will begin in ISO 8601 format (YYYY-MM-DD or YYYYMMD; order will last until endDate, when specified

For non CMA9-specific standing orders involving a CMA9 bank, startDate maps to firstPaymentDateTime, consistent with the OBIE standard.

traceID Optional 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.
transferDestinations Required These are the beneficiary account details.

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

* CMA9-specific standing order only. Either numberOfPayments or finalPaymentDateTime must be specified (not both) if the domestic standing order is not open ended.

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.

Reflecting the request details and adding the Token-assigned request ID (id), the response takes the following form:

"tokenRequest": {

    "id": "rq:3eoe4MPXkUGEA3gWeMTDWPTKAfxU:5zKtXEAq", // request-id; add to BASE_URL for consent

    "requestPayload": {

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

        "to": {

            "alias": {

                "type": "EMAIL",

                "value": noverify@token.io"

            }

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"// TPPmember ID

        },

        "standingOrderBody": {

              "instructions": {

                  "metadata": {

                  },

                  "transferDestinations": [{

                      "sepa": {

                          "bic": "123456",

                          "iban": "IT12345678"

                      },

                      "customerData": {

                          "legalNames": ["Southside"]

                      }

                  }]

              },

              "startDate": "2019-12-16",

              "endDate": "2019-12-20",

              "frequency": "DAIL",

              "amount": "7.96",

              "currency": "EUR"

        },

        "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:3eoe4MPXkUGEA3gWeMTDWPTKAfxU:5zKtXEAq

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

For Auth PLUS Transfer payments, you'll need to redeem the transfer token with a POST /transfer request containing the Token-provided tokenId. Here's an example:

{

 "tokenId": "tokenId":"st:5vwpSZXLy4pHnD5dtc9B1Hta7TrzqYZX8A5X66xxU7hn:5zKcENpV"

}

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.