Single Immediate Payments

A single immediate payment (SIP) is a payment initiated on behalf of a user for immediate execution. There are, however, certain restrictions imposed by the various payment systems. For instance, SEPA transfers have a 3:00 pm cutoff time for same day processing. Requests received after this time will be processed the following business day. It's also important to note that, as a general rule, sending euros outside the UK using SEPA can take up to 2 business days before being credited to the beneficiary bank, although in most cases the money arrives in the beneficiary's bank account on the next business day.

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 SIP

Note: We support immediate transfer token redemption through Bank-initiated payments.

For information regarding TPP-initiated (2-step) payments, please see Optional features.

The following diagram shows the communication flow for a Bank-initiated single immediate payment (click to enlarge):

For payment 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 (click to enlarge).

If the mandatory user credentials you provide are invalid, the 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 next.

Base URLs

See Base URLs.

Headers

See Common Request Headers.

Making a Transfer 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 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.

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 a simplified call for POSTing /token-requests with a requestPayload:

{

    "requestPayload": {

        "refId": "xyz", // must be unique

        "to": {

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // required TPP member ID; mandatory

         },

        "transferBody": {

            "currency": "EUR",

            "lifetimeAmount": "1.00",

            "instructions": {

                "transferDestinations": [

                     {

                         "sepa": {

                              "iban": "FR7630004001160000784013521"

                         },

                         "customerData": {

                             "legalNames": [

                                 "Test" // populating creditor name is mandatory

                             ]

                         }

                    }

                ]

            }

        },

        "description": "your description",

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

    }

}

"Available from Dashboard" indicates a value that can be looked up in the Dashboard under Settings > Member Information.

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. Required
to Identifies the member initiating the request Required
id Member ID of the TPP, a constant value in all requests; see Member Information in Understanding Dashboard Settings. 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
transferBody Specifies the critical details of the transfer payload: currency, lifetimeAmount, and transferDestinations (beneficiary account information). Required
currency ISO 4217 currency code for the transaction Required
lifetimeAmount Amount of the payment/transfer valued in currency.

Precision: Recommended precision is rounding to 4 decimal places (HALF-EVEN), 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, SEPA, or cross-border payment. Generally, the beneficiary is the TPP. See Restricting Beneficiary Accounts for guidance on adding, modifying, and deleting accounts.

Each restricted 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

source Identifies the bank account from which the amount is being debited; set using the AccountIdentifier object, See Source Account Validation for important rules about populating the source object.
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%
3A5zKtXEAq%22%2C%22keyId%22%3A%22lgf2Mn0G4kkcXd5m%22%2C%22signature%22%3A%22Md-2D
G0X9PpuOxea0iK33cAZ2Ffk6E5I1mAcJS6YywU80Q0yYBOlwvGy37dmovmH_OC7Jl8c-fxQ5gP2RWTaDw%22%7D&
state=%257B%2522csrfTokenHash%2522%253A%2522pod1e6xornyoesn2sp%2522%257D&
tokenId=ta%3AHWowFawmAwiuPKNdM7xjpiQktPppgK2JatsWPZAyTHcq%3A5zKtXEAq

Optional
description Description of the payment with the following qualifiers:
  • must comply with the constraint imposed by the bank (see Bank-dependent Field Formatting)
  • length must be no greater than 255 characters
  • 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
disableFutureDatedPaymentConversion Explicitly disables conversion of an auto single immediate payment to a future-dated payment for requests sent during the bank's out-of-operation hours. Default = false, which means always allow auto SIP to FDP conversion. Set to true, conversion is disabled Optional
redirectUrl Defines the bank's callback URL where your server initiates token redemption. Required
remittanceReference Augmenting refId and description, this is TPP-defined additional information pertinent to TPP's payments policies; for instance, 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 lifecycle as an audit-trail aid. Optional
requestOptions
  • bankId where payment is to be initiated
  • psuId of customer initiating the payment; recommended to identify group payments initiated by the same user
  • receiptRequested – to specify that an email receipt is to be sent to the user by Token.io
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": {

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

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

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:

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

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

            "transferInstructions": {

                "transferDestinations": {

                     "fasterPayments": {

                         "accountNumber": "70000005",

                         "sortCode": "700001"

                     }

                }

            }

        },

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

https://{{BASE_URL}}/app/request-token/{{Insert request-id here}}

// example = https://web-app.sandbox.token.io/app/request-token/rq:3RKfCA7KQEEZERLoFsAt3MoAnoP5: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?lang=de

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 either a tokenId (also known as the consentId on the bank side) 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

To derive the complete redirect URL, you'll need to URL decode the tokenId or transferId value provided.

Using the tokenId sent by the bank, which confirms user consent, you can now initiate payment.

If the bank supports 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. See Fetching the Status of a Payment below for more on this.

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

{

 "payload": {

    "tokenId": "{{TOKEN_ID}}", // tokenId in redirectUrl

  }

}

The request field and its corresponding description are listed in the following table.

Field Description/Subfields Required/Optional
payload tokenId Bank-generated identifier returned in the response to the original payment request Required

You'll receive a transferId and transferStatus in a callback, which you can then display to the customer/user.

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

To get information about a specific token, use a GET /tokens/{tokenId} call.

Please refer to the Token.io's API reference for additional details on all of the above.

Single Immediate Payments

A single immediate payment (SIP) is a payment initiated on behalf of a user for immediate execution. There are, however, certain restrictions imposed by the various payment systems. For instance, SEPA transfers have a 3:00 pm cutoff time for same day processing. Requests received after this time will be processed the following business day. It's also important to note that, as a general rule, sending euros outside the UK using SEPA can take up to 2 business days before being credited to the beneficiary bank, although in most cases the money arrives in the beneficiary's bank account on the next business day.

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 SIP

Note: We support immediate transfer token redemption through Bank-initiated payments.

For information regarding TPP-initiated (2-step) payments, please see Optional features.

The following diagram shows the communication flow for a Bank-initiated single immediate payment (click to enlarge):

For payment 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 (click to enlarge).

If the mandatory user credentials you provide are invalid, the 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 next.

Base URLs

See Base URLs.

Headers

See Common Request Headers.

Making a Transfer 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 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.

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 a simplified call for POSTing /token-requests with a requestPayload:

{

    "requestPayload": {

        "refId": "xyz", // must be unique

        "to": {

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // required TPP member ID; mandatory

         },

        "transferBody": {

            "currency": "EUR",

            "lifetimeAmount": "1.00",

            "instructions": {

                "transferDestinations": [

                     {

                         "sepa": {

                              "iban": "FR7630004001160000784013521"

                         },

                         "customerData": {

                             "legalNames": [

                                 "Test" // populating creditor name is mandatory

                             ]

                         }

                    }

                ]

            }

        },

        "description": "your description",

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

    }

}

"Available from Dashboard" indicates a value that can be looked up in the Dashboard under Settings > Member Information.

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. Required
to Identifies the member initiating the request Required
id Member ID of the TPP, a constant value in all requests; see Member Information in Understanding Dashboard Settings. 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
transferBody Specifies the critical details of the transfer payload: currency, lifetimeAmount, and transferDestinations (beneficiary account information). Required
currency ISO 4217 currency code for the transaction Required
lifetimeAmount Amount of the payment/transfer valued in currency.

Precision: Recommended precision is rounding to 4 decimal places (HALF-EVEN), 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, SEPA, or cross-border payment. Generally, the beneficiary is the TPP. See Restricting Beneficiary Accounts for guidance on adding, modifying, and deleting accounts.

Each restricted 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

source Identifies the bank account from which the amount is being debited; set using the AccountIdentifier object, See Source Account Validation for important rules about populating the source object.
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%
3A5zKtXEAq%22%2C%22keyId%22%3A%22lgf2Mn0G4kkcXd5m%22%2C%22signature%22%3A%22Md-2D
G0X9PpuOxea0iK33cAZ2Ffk6E5I1mAcJS6YywU80Q0yYBOlwvGy37dmovmH_OC7Jl8c-fxQ5gP2RWTaDw%22%7D&
state=%257B%2522csrfTokenHash%2522%253A%2522pod1e6xornyoesn2sp%2522%257D&
tokenId=ta%3AHWowFawmAwiuPKNdM7xjpiQktPppgK2JatsWPZAyTHcq%3A5zKtXEAq

Optional
description Description of the payment with the following qualifiers:
  • must comply with the constraint imposed by the bank (see Bank-dependent Field Formatting)
  • length must be no greater than 255 characters
  • 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
disableFutureDatedPaymentConversion Explicitly disables conversion of an auto single immediate payment to a future-dated payment for requests sent during the bank's out-of-operation hours. Default = false, which means always allow auto SIP to FDP conversion. Set to true, conversion is disabled Optional
redirectUrl Defines the bank's callback URL where your server initiates token redemption. Required
remittanceReference Augmenting refId and description, this is TPP-defined additional information pertinent to TPP's payments policies; for instance, 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 lifecycle as an audit-trail aid. Optional
requestOptions
  • bankId where payment is to be initiated
  • psuId of customer initiating the payment; recommended to identify group payments initiated by the same user
  • receiptRequested – to specify that an email receipt is to be sent to the user by Token.io
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": {

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

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

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:

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

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

            "transferInstructions": {

                "transferDestinations": {

                     "fasterPayments": {

                         "accountNumber": "70000005",

                         "sortCode": "700001"

                     }

                }

            }

        },

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

https://{{BASE_URL}}/app/request-token/{{Insert request-id here}}

// example = https://web-app.sandbox.token.io/app/request-token/rq:3RKfCA7KQEEZERLoFsAt3MoAnoP5: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?lang=de

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 either a tokenId (also known as the consentId on the bank side) 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

To derive the complete redirect URL, you'll need to URL decode the tokenId or transferId value provided.

Using the tokenId sent by the bank, which confirms user consent, you can now initiate payment.

If the bank supports 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. See Fetching the Status of a Payment below for more on this.

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

{

 "payload": {

    "tokenId": "{{TOKEN_ID}}", // tokenId in redirectUrl

  }

}

The request field and its corresponding description are listed in the following table.

Field Description/Subfields Required/Optional
payload tokenId Bank-generated identifier returned in the response to the original payment request Required

You'll receive a transferId and transferStatus in a callback, which you can then display to the customer/user.

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

To get information about a specific token, use a GET /tokens/{tokenId} call.

Please refer to the Token.io's API reference for additional details on all of the above.

Single Immediate Payments

A single immediate payment (SIP) is a payment initiated on behalf of a user for immediate execution. There are, however, certain restrictions imposed by the various payment systems. For instance, SEPA transfers have a 3:00 pm cutoff time for same day processing. Requests received after this time will be processed the following business day. It's also important to note that, as a general rule, sending euros outside the UK using SEPA can take up to 2 business days before being credited to the beneficiary bank, although in most cases the money arrives in the beneficiary's bank account on the next business day.

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 SIP

Note: We support immediate transfer token redemption through Bank-initiated payments.

For information regarding TPP-initiated (2-step) payments, please see Optional features.

The following diagram shows the communication flow for a Bank-initiated single immediate payment (click to enlarge):

For payment 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 (click to enlarge).

If the mandatory user credentials you provide are invalid, the 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 next.

Base URLs

See Base URLs.

Headers

See Common Request Headers.

Making a Transfer 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 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.

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 a simplified call for POSTing /token-requests with a requestPayload:

{

    "requestPayload": {

        "refId": "xyz", // must be unique

        "to": {

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // required TPP member ID; mandatory

         },

        "transferBody": {

            "currency": "EUR",

            "lifetimeAmount": "1.00",

            "instructions": {

                "transferDestinations": [

                     {

                         "sepa": {

                              "iban": "FR7630004001160000784013521"

                         },

                         "customerData": {

                             "legalNames": [

                                 "Test" // populating creditor name is mandatory

                             ]

                         }

                    }

                ]

            }

        },

        "description": "your description",

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

    }

}

"Available from Dashboard" indicates a value that can be looked up in the Dashboard under Settings > Member Information.

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. Required
to Identifies the member initiating the request Required
id Member ID of the TPP, a constant value in all requests; see Member Information in Understanding Dashboard Settings. 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
transferBody Specifies the critical details of the transfer payload: currency, lifetimeAmount, and transferDestinations (beneficiary account information). Required
currency ISO 4217 currency code for the transaction Required
lifetimeAmount Amount of the payment/transfer valued in currency.

Precision: Recommended precision is rounding to 4 decimal places (HALF-EVEN), 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, SEPA, or cross-border payment. Generally, the beneficiary is the TPP. See Restricting Beneficiary Accounts for guidance on adding, modifying, and deleting accounts.

Each restricted 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

source Identifies the bank account from which the amount is being debited; set using the AccountIdentifier object, See Source Account Validation for important rules about populating the source object.
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%
3A5zKtXEAq%22%2C%22keyId%22%3A%22lgf2Mn0G4kkcXd5m%22%2C%22signature%22%3A%22Md-2D
G0X9PpuOxea0iK33cAZ2Ffk6E5I1mAcJS6YywU80Q0yYBOlwvGy37dmovmH_OC7Jl8c-fxQ5gP2RWTaDw%22%7D&
state=%257B%2522csrfTokenHash%2522%253A%2522pod1e6xornyoesn2sp%2522%257D&
tokenId=ta%3AHWowFawmAwiuPKNdM7xjpiQktPppgK2JatsWPZAyTHcq%3A5zKtXEAq

Optional
description Description of the payment with the following qualifiers:
  • must comply with the constraint imposed by the bank (see Bank-dependent Field Formatting)
  • length must be no greater than 255 characters
  • 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
disableFutureDatedPaymentConversion Explicitly disables conversion of an auto single immediate payment to a future-dated payment for requests sent during the bank's out-of-operation hours. Default = false, which means always allow auto SIP to FDP conversion. Set to true, conversion is disabled Optional
redirectUrl Defines the bank's callback URL where your server initiates token redemption. Required
remittanceReference Augmenting refId and description, this is TPP-defined additional information pertinent to TPP's payments policies; for instance, 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 lifecycle as an audit-trail aid. Optional
requestOptions
  • bankId where payment is to be initiated
  • psuId of customer initiating the payment; recommended to identify group payments initiated by the same user
  • receiptRequested – to specify that an email receipt is to be sent to the user by Token.io
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": {

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

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

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:

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

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

            "transferInstructions": {

                "transferDestinations": {

                     "fasterPayments": {

                         "accountNumber": "70000005",

                         "sortCode": "700001"

                     }

                }

            }

        },

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

https://{{BASE_URL}}/app/request-token/{{Insert request-id here}}

// example = https://web-app.sandbox.token.io/app/request-token/rq:3RKfCA7KQEEZERLoFsAt3MoAnoP5: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?lang=de

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 either a tokenId (also known as the consentId on the bank side) 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

To derive the complete redirect URL, you'll need to URL decode the tokenId or transferId value provided.

Using the tokenId sent by the bank, which confirms user consent, you can now initiate payment.

If the bank supports 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. See Fetching the Status of a Payment below for more on this.

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

{

 "payload": {

    "tokenId": "{{TOKEN_ID}}", // tokenId in redirectUrl

  }

}

The request field and its corresponding description are listed in the following table.

Field Description/Subfields Required/Optional
payload tokenId Bank-generated identifier returned in the response to the original payment request Required

You'll receive a transferId and transferStatus in a callback, which you can then display to the customer/user.

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

To get information about a specific token, use a GET /tokens/{tokenId} call.

Please refer to the Token.io's API reference for additional details on all of the above.

 

 

© 2023 TOKEN, INC.     ALL RIGHTS RESERVED.