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

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 Standing Order Submission (1-step)

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

TPP-initiated Standing Order Submission (2-step)

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

For payment requests subject to mandatoryFields and the correct field mapping, see the discussion on mapping mandatory fields.

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 API 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 labelled as such in the list of key fields.

To test OBIE-CMA9 standing orders, please use Ozone Bank.

Base URLs

See Base URLs.

Headers

See Common Request Headers.

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

        },

        "standingOrderBody": {

                "transferInstructions": {

                    "metadata": {        // see notes on provider metadata below

                    },

                    "transferDestinations": {

                        "fasterPayments": {

                            "accountNumber": "70000005",

                            "sortCode": "700001"

                        }

                    },

                         "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 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
standingOrderBody Specifies the critical details of the standing order: currency, amount, and transferDestinations(beneficiary account information). Required
currency Currency for the transaction Required
amount Payment amount valued in currency for each scheduled transfer.

For standing orders involving standard (non-variable) payments from a 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. 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.

Required
frequency 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 instalment 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 instalments will occur on the 5th day of each succeeding month), unless startDate is the last day of the month. If so, all subsequent monthly instalments will occur on the last day of each month.
Required
startDate 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.

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

Supported by CMA9 banks only
firstPaymentDateTime Scheduled date and time for firstPayment in accordance with the OBIE standard. Supported by CMA9 banks only
nextPayment Recurring instalment payment amount scheduled by nextPaymentDateTime and frequency in accordance with the OBIE standard. Supported by CMA9 banks only
nextPaymentDateTime Recurring payment date and time for instalments scheduled between firstPaymentDateTime and finalPaymentDateTime in accordance with the OBIE standard. Supported by CMA9 banks only
payment_amount Recurring payment amount for scheduled instalments 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. Supported by CMA9 banks only
payment_date_time Recurring payment date and time for instalments scheduled between startDate and endDate in accordance with the OBIE standard. If not specified for CMA9 orders, scheduled instalments will default in accordance to the day/date ascribed to frequency (see the note above). Supported by CMA9 banks only
number_of_payments int32 field specifying the total number of payments in accordance with the OBIE standard. Required if finalPaymentDateTime is not specified. Supported by CMA9 banks only
finalPayment 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.

Supported by CMA9 banks only
finalPaymentDateTime Scheduled date and time for finalPayment in accordance with the OBIE standard. Required if numberOfPayments is not specified. Supported by CMA9 banks only
endDate Specifies the ending 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.

Required
remittanceInformation Creditor reference or payment remit identification for end-to-end transaction identification in accordance with the OBIE standard. Supported by CMA9 banks only
transferInstructions Instructions to the bank for executing the transactions.
metadataBank-dependent; can include deliveryAddress, merchant identification, and provider information specific to this standing order — type of standing order (cma9StandingOrderMetadata, nextGenPsd2StandingOrderMetadata, polishApiStandingOrderMetadata, or stetStandingOrderMetadata), payment value and scheduling parameters (firstPayment, recurringPayment, and/or finalPayment), and so forth. See Notes on provider metadata below.
transferDestinationsThese 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.

Each whitelisted destination/beneficiary account is specified according to the payment system used. See Initiating Payments for the list of supported payment systems and the respective account information fields required.

Required by some banks, optional for others, the type of destination account (business or personal) is specified under transferDestinations in customerData.type as UNKNOWN, BUSINESS or PERSONAL. When not specified, the default destination account type is BUSINESS.

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

sourceAccount number from which the amount is being debited; set using the AccountIdentifier object, which allows four types of account identifiers:

Note: In EU countries that don't use the euro as their domestic currency, iban should be used for domestic source accounts, with the exception of Sweden. For Swedish domestic, the accountIdentifier can be either bankgiro or plusgiro. Specify a plusgiroNumber for the plusgiro payment rail. If the payment rail is bankgiro, provide a bankgiroNnumber.

source is required for one-step payment; optional for two-step payment

Required*
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:

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. Required
remittanceReference Augments refId and description, this is TPP-defined additional information pertinent to the 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
traceID TPP-provided unique value captured by Token and sent across to the bank to be stored with the request throughout its life-cycle as an audit-trail aid. 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
* 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": {

    "accountIdentifier": {

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

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.

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

actingAs: {

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

Properties of the actingAs Field
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: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": {

                      "fasterPayments": {

                          "accountNumber": "70000005",

                          "sortCode": "700001"

                      }

                  },

                  "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/{{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 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 webapp URLClosedUniform 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 (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 tokenId or a transferId 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

Using the tokenId sent by the bank (also known as the consent-id on the bank side), 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 2-step payments, you'll need to redeem the transfer token with a POST /standing-order-submissions request containing the Token-provided tokenId from the bank's response. Here's an example:

{

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

}

With the exception of GET /banks, all POST and GET calls must pass in an appropriate authorisation header containing your authentication key (see Common Request Headers).

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 Object and Field Definitions and Swagger Specification for additional details on all of the above.