Single Immediate Payments

A single immediate payment (SIP) is a payment initiated on behalf of a user for immediate execution.

Bank-initiated SIP

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

E-merchant-initiated SIP (2-step)

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

Note: If you would prefer to use the auto redeem functionality to automatically redeem authentication tokens for 2-step payments, see Optional features for more information.

Guidance for making the appropriate POST and GET calls, as well as handling the bank'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 e-merchant using your Member ID — a unique value generated by the Dashboard when you signed up.

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.

Here's a simplified call for POSTing /token-requests with a requestPayload:

POST {{BASE_URL}}/token-requests

{

    "requestPayload": {

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

        "to": {

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq" // required e-merchant 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 Merchant-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 corresponds to the endToEndId described in the STET standard, a unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

We recommend that only alphanumeric characters are used and that special characters are avoided.

Required
to Identifies the member initiating the request Required
alias A human-readable proxy for your member identifier that contains your realmId or alias type (DOMAIN, EMAIL, other) and a value string. Optional; soon to be deprecated
transferBody Specifies the critical details of the transfer payload: currency, lifetimeAmount, and transferDestinations . 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 Generally, the beneficiary is the e-merchant and the primary transfer destination is the e-merchant's bank account. In every request, the destination information sent is validated against the account information provided through beneficiary management in the dashboard. The valid payment rail values are sepa and sepa_instant, both of which require the beneficiary iban.

Note: Only provide transfer destinations for accounts pre-configured by BNPP or the request will fail.
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 the bank; 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:
  • length must be no greater than 50 characters banks using the STET standard and 255 characters for banks using other standards

description corresponds to remittanceInformation described in the STET standard. It is information supplied to enable matching an entry with items the transfer is intended to settle, such as commercial invoices in an accounts receivable system.

We recommend that only alphanumeric characters are used and that special characters are avoided.

BNP Paribas recommends that e-merchants use the description and refId fields for their customized transaction references to ensure that these references appear in their bank statements.

 Optional, with the caveats described in the previous column
redirectUrl Defines the e-merchant's callback URL. Required
traceID TPP-provided unique value captured by Token.io 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 BNP Paribas
 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

Creditor account (payee) information (legal name and/or address) is included in customerData within providerTransactionDetails for single transactions. The API standard requires that payee/creditor information be included in all payment requests.

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.io counterpart as follows:

Token.io OBIE
flats SubDepartment
house_name Department
house_number BuildingNumber
street StreetName
post_code PostCode
city TownName
district CountrySubDivision
country Country

 

Processing the Response

Here's an example of the response you'll receive:

Response to transfer token request

"tokenRequest": {

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

    "requestPayload": {

        "to": {

            "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"// e-merchant member ID

        },

        "transferBody": {

            "currency": "EUR",

            "lifetimeAmount": "10",

            "transferInstructions": {

                "transferDestinations": {

                     "fasterPayments": {

                         "accountNumber": "70000005",

                         "sortCode": "700001"

                     }

                }

            }

        },

        "description": "your description",

        "redirectUrl": "https://sample-emerchant-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

Upon user consent, the bank will redirect the user back to the e-merchant with either a tokenId (also known as the consentId on the bank side) or a transferId as a query parameter.

"redirectUrl": "https://sample-merchant-domain.com"/pis?tokenId=sample_token_id

"redirectUrl": "https://sample-emerchant-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 the bank-provided tokenId. Here's an example:

POST {{BASE_URL}}/transfers

{

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

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 API reference for additional details on all of the above.