Standing Orders

A standing order token is used for recurring payments (installments) scheduled at regular intervals. 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).

You must also specify the startDate of the order, as well as the endDate, unless you want payments to continue indefinitely (not recommended).

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

CMA9 Standing Orders: The SDK also supports the more granular frequency settings for standing orders required by the CMA9v3ClosedAs 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 transfer token request fields below.

To test CMA9v3 standing orders, please use Ozone Bank.

Once the token request is created, you store it, awaiting a corresponding request-id, which is returned by Token in a response payload. In addition to the request-id, the response payload reflects all the information you included in your original request.

Now equipped with the request-id, you can set your transfer destination(s), if you omitted a destination in the originating request, and redeem the token, thereby transferring the specified payment amount from the payer's bank account to the payee's bank account on the dates scheduled by startDate and frequency; or — for CMA9-specific orders — first_payment_date_time, next_payment_date_time, and final_payment_date_time for their respective (variable) amounts.

Tip: Remember, in the examples that follow, classes, methods and parameters are initially presented in their default Java syntax. Select the corresponding tab — Java, JavaScript or C# in the navigation bar — to display the correct syntax and field names for the SDK language chosen.

For standing orders, replace transferTokenRequestBuilder() used for the previous payment types (single immediate and future-dated) with standingOrderRequestBuilder(). Here's a sample structure for a standing order request call:

private static String initializeStandingOrderTokenRequestUrl(

        Map<String, String> params,

        String callbackUrl, Response response) {

    double amount = Double.parseDouble(params.get("amount"));

    String currency = params.get("currency");

    String description = params.get("description");

    TransferDestination destination = TransferDestination.newBuilder()

        .setSepa(TransferDestination.Sepa.newBuilder().setBic("bic")

        .setIban("DE16700222000072880129").build())

        .setCustomerData(TransferInstructionsProtos.CustomerData.newBuilder()

        .addLegalNames("merchant-sample-java").build())

        .build();

    LocalDate startDate = LocalDate.now();

    LocalDate endDate = startDate.plusYears(1);

    String refId = generateNonce();

 

    // generate CSRF token

    String csrfToken = generateNonce();

    // set CSRF token in browser cookie

    response.cookie(CSRF_TOKEN_KEY, csrfToken);

 

   // create the token request

   TokenRequest request = TokenRequest

        .standingOrderRequestBuilder(amount, currency, "MNTH", startDate.toString(),

             endDate.toString(), Collections.singletonList(destination))

        .setDescription(description).setRefId(refId)

        .setToAlias(merchantMember.firstAliasBlocking())

        .setToMemberId(merchantMember.memberId()).setRedirectUrl(callbackUrl)

        .setCsrfToken(csrfToken) // validates the session ID

        // use keys in bank authorization metadata from getBanks() response

        .putAllAuthorizationMetadata(new HashMap<>())

        .build();

 

   // now store the token request

   String requestId = merchantMember.storeTokenRequestBlocking(request);

}

Shown above, the key fields comprising a token request for a standing order are defined in the following table.

Fields in a Transfer Token Request for Standing Orders
Field Description Required/ Optional
actingAs Party or entity for which the to member is acting as a proxy. See Creating a Token on Behalf of another Party for details on setting the properties for this field. Optional
amount

Payment value calculated 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, amount maps to first_payment, 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 its 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
authorizationMetadata 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. Maps the key-value pairs from the getBanks() response, where key is the name of the field and value is the value of the field. Required
bankId When specified, indicates you wish to bypass the Token bank selection UI and use your own bank selection UI for the request. See Using the getbanks Method. Optional
callBackState TPP-specified string that persists state between request and callback. Optional, but recommended
creditor_account CMA9-specific standing orders only. Payee'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. to which funds will be transferred. Required
currency ISO 4217 alpha-3 currency code. Required
customizationId Identifier for customizing the UI of the Token web app (see Customising the Token Webapp for details). Optional
description

Description of the standing order 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: A description mismatch between the originating TPP token request and subsequent token lookups/changes/updates (retrieve, redeem, or cancel) will throw an exception.

Optional
endDate 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 final_payment_date_time, consistent with the OBIE standard.
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 installment will be based on the day of week for startDate (standard) or first_payment_date_time (CMA9-specific). For instance, if the date 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 for standard orders (next_payment_date_time for CMA9-specific orders). Hence, if the date is the 5th of the month, all monthly installments will occur on the 5th day of each succeeding month), unless the date is the last day of the month. If so, all subsequent monthly installments will occur on the last day of each month.
Required
from member_id or alias of the user; if included, indicates you wish to bypass the Token user email entry UI. Optional
member The customer/user; payer of the token. Required
ProviderTransferMetadata Adds metadataClosedData that provide information about other data or summarises basic information about data. for the specified provider. Optional
receiptRequested Boolean; requests a receipt be sent to the from member's default email address. Optional
final_payment

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

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 its 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
final_payment_date_time CMA9-specific standing orders only. Scheduled date and time for final_payment in accordance with the OBIE standard. Required if number_of_payments is not specified. Required*
first_payment

CMA9-specific standing orders only. First or "down" payment in accordance with the OBIE standard. Value can be a different amount with respect to next_payment and final_payment.

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 its 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
first_payment_date_time CMA9-specific standing orders only. Scheduled date and time for first_payment in accordance with the OBIE standard. Required
next_payment

CMA9-specific standing orders only. Recurring installment payment amount scheduled by next_payment_date_time and frequency in accordance with the OBIE 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 its 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
next_payment_date_time CMA9-specific standing orders only. CMA9 recurring payment date and time for installments scheduled between first_payment_date_time and final_payment_date_time in accordance with the OBIE standard. Required
number_of_payments CMA9-specific standing orders only. int32 field specifying the total number of payments in accordance with the OBIE standard. Required if final_payment_date_time is not specified. Required*
redirectUrl Specifies the callback URL where your server will initiate token redemption. Required
refId

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: A description mismatch between the originating token request and subsequent token lookups/changes/updates (retrieve, redeem, or cancel) will throw an exception.

Required
remittance_information CMA9-specfic standing orders only. Creditor reference or payment remit identification for end-to-end transaction identification in accordance with the OBIE standard. Optional
risk CMA9-specfic standing orders only. Used to specify additional details for risk scoring in accordance with the OBIE standard. Optional
sourceAccountId Identifier of the source bank account — the user's bank account — e.g., "Main Checking" Optional
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 first_payment_date_time, consistent with the OBIE standard.
Required
to member_id and alias of the transfer recipient Required
token_expiration Sets the expiration date and time for the token request (default is 20 minutes); override of default value is not supported by all banks. 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
transferDestinations Payment beneficiary bank account(s); where payment will be sent. Typically an 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. for 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 SORT codeClosedNumber code used by British and Irish banks using six digits divided into three different pairs; for instance, 12-34-56. These codes, like many other bank codes, are used to identify the location of the bank where the account is held. The first two digits are usually bank identifiers. However, in some cases, the first code may describe the bank as well. It must be noted that the SORT code of a bank is integrated and encoded in the IBAN number of the account but not in the BIC codes of the account. A SORT code is used by banks to identify and route the money transfers to the respective bank and account. SORT codes are also called NSC or National SORT Code in Ireland and are regulated by the IPSO (Irish Payment Services Organization). A SORT Code in Ireland begins with the digit “9”. and Account Number(s) for FPSClosedFaster Payments Service – UK banking initiative to reduce payment times between different banks' customer accounts from the three working days that transfers take using the long-established BACS system to typically a few seconds.. See Beneficiary Account Details for supported instruments. Required
userRefId Identifier that can be used to track a user member claimed by the TPP. Optional
* CMA9-specific standing order only. Either number_of_payments or final_payment_date_time must be specified (not both) if the domestic standing order is not open ended.

As with single payments (immediate and future-dated), you can store the created request without a transfer destination and, instead, specify a transferDestinationsCallback URL for Token to call upon customer authentication and authorisation. Or you can specify the destination when you redeem the token. Additional details can be found in Setting Transfer Destinations.