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 user'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 authorize 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).
Before initiating a request to a Token.io-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 /v2/banks call filters the list of Token.io-connected banks based on your selection criteria with respect to bank location and bank-supported features. See Bank Selection 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 (click to enlarge) shows the communication flow for submitting a
TPP-initiated Standing Order Submission (2-step)
The sequence diagram pictured next shows the communication flow for a TPP-initiated SIP.
Heads-up: For standing order requests subject to additional credentials in mandatoryFields, see the discussion on mapping mandatory fields in bank selection for the correct field mapping, paying special attention to the differences in authenticating credentials in the respective request flows; i.e., using the Token Web App versus not using the Token Web App.
If the mandatory user credentials you provide are invalid, the submission status returned will be unauthenticated, and you will need to repeat the redirect to the bank for consent to have your user try again. Conversely, when the status returned is authenticated, it means the bank has accepted the consent and no redirect is required.
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 CMA9 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
Making the Token Request
To initiate a payment request with the bank, you'll need to be able to identify yourself as the calling
- Member ID – unique value generated by the 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:
-
If the dashboard isn't already open in a browser tab, sign in.
-
Click Member Information in the navigation panel on the left.
-
Click the "eye" icon to the right of each value to reveal it.
-
Copy the value you need.
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 ) in its response to your GET /banks call (see Bank Selection) 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.
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 user gives consent for you to initiate PIS on the user's behalf, here's the call for POSTing /token-requests with a requestPayload:
{
"requestPayload": {
"refId": "xyz", // must be unique
"to": {
"id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // required member ID; mandatory
},
"standingOrderBody": {
"transferInstructions": {
"metadata": { // see notes on provider metadata below
},
"transferDestinations": {
"fasterPayments": {
"accountNumber": "70000005",
"sortCode": "700001"
},
"customerData": {
"legalNames": [
"Test"
] // populating creditor name is mandatory
}
},
},
"startDate": "2019-12-16",
"endDate": "2019-12-20",
"frequency": "DAIL",
"amount": "7.96",
"currency": "EUR"
},
"description": "your description",
"redirectUrl": "https://sample-merchant-domain.com/transfer"
},
"requestOptions": {
"from": {
}
}
The most important request fields and their corresponding descriptions are listed in the following table.
| Field | Description/Subfields | Required/Optional | ||||||
|---|---|---|---|---|---|---|---|---|
| refId |
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 | ||||||
| id | Member ID of the |
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. |
Optional; soon to be deprecated | ||||||
| standingOrderBody | Specifies the critical details of the standing order: currency, amount, and transferDestinations |
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 bank, lifetimeAmount maps to firstPayment, consistent with the standard. Precision: Recommended precision is rounding to 4 decimal places (), 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 (), 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 OBIE 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 (), 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 | ||||||
| instructions |
Instructions to the bank for executing the transactions.
|
Required* | ||||||
| callbackState |
Developer-specified string allowing state to be persisted between the request and callback phases of the flow; used for the signature in a GET /token-requests/{tokenRequestId}/token-request-result call, in which the signing payload for the signature is a combination of state and tokenId and validates the tokenId against the callbackstate originally sent by the TPP in the request. Note: The value of callbackState is added to the redirect URL and appended to the hash of the CSRF token specified by Token.io; e.g.: https://{callback-url}?signature=%7B%22memberId%22%3A%22m%3A3rKtsoKaE1QUti3KCWPrcSQYvJj9% |
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 |
Required | ||||||
| remittanceReference |
Augments refId and description, this is |
Optional | ||||||
| traceID |
|
Optional | ||||||
| requestOptions |
|
Optional | ||||||
| * Inclusion of some elements may be optional or bank-dependent | ||||||||
Cited in the table within transferInstructions and nested in source is the accountIdentifier object (required):
"source": {
"": {
"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.
A PAN is disallowed in the token request payload within the refId and description fields. In accordance with the PA-DSS security standard, Regex 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.
Payee Information
customerData within providerTransactionDetails for single transactions.
-
STET requires creditor account information.
-
CMA9, NextGenPSD2, and PolishAPI have the creditor name and account identifiers, as well as the creditor agent BIC. However, these are optional fields, so the presence of creditor account information is bank-dependent.
-
CMA9 needs the creditor agent address, whilst PolishAPI requires the creditor's address.
If you are initiating a payment to Barclays Bank UK or HSBC, the creditor name (creditorAcount.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 OBIE 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
|
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:
: {
"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:
| 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"// member 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": "your description",
"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
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 Web App according to personal preference. Here's an example for passing the desired ISO 639-1 language code for German (de):
https://web-app.token.io/app/request-token/rq:o9adbFqJXcaDGNDaykPvpSZFZDW:5zKtXEAq?
TPPs using Token's licence only: This Web App URL redirects the PSU to the Token Web App, which displays a payment confirmation page (pictured, click 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 (IBAN).
Upon user consent, Token.io will redirect the user back to the TPP with
"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 decode the tokenIdtransferId value provided.
Using the tokenId sent by the bank (also known as the consent-id on the bank side), which confirms user consent, you can now initiate payment.
{
"tokenId": "tokenId":"st:5vwpSZXLy4pHnD5dtc9B1Hta7TrzqYZX8A5X66xxU7hn:5zKcENpV"
}
GET /banks, all POST and GET calls must pass in an appropriate authorization header containing your authentication key (see Common Request Headers).
Please refer to the Token.io's API reference for additional details on all of the above.
