Skip to content
Single Immediate Payments...
/
/
Account on File
Last updated

Account on file

Overview

The Account on File feature enables Token’s clients to securely tokenise a payment service user’s (PSU’s) bank account information. This allows merchants and third-party providers (TPPs) to reference a user’s account via a unique token, rather than handling sensitive account details (such as IBAN or account number and sort code) directly. The result is a streamlined payment experience, improved compliance, and reduced friction for returning users.

This feature is inspired by the “card-on-file” experience familiar from card payments, but adapted for open banking and account-based payments.


Key benefits

  • For users: No need to re-enter bank details for repeat payments, leading to a seamless checkout experience

  • For merchants: Higher conversion rates and improved user retention

    • Increase in conversion rates for

      1. Banks in Italy and Spain by saving PSU information returned by bank

      2. Removes the need for PSU to provide IBAN when a request is made to a bank that requires IBAN as a mandatory field. This will cover many countries including Germany, Austria, the Nordics and Hungary

    • Reduce fraudulent attempts using Open Banking payments

    • By simplifying user experience (reduce number of steps), increase conversion rates for customers using the Web-App and the API

What is Account Tokenisation?

Account tokenisation is the process of replacing sensitive account details with a unique, non-sensitive identifier (the “tokenised account ID”). This ID can be used in subsequent payment requests, removing the need to transmit or store raw account details.

User Journey


First-Time Payment

  1. The user selects “Pay by Bank” at checkout.

  2. The merchant or TPP initiates a payment request, including the user’s account details (IBAN or account number + sort code) and a flag indicating that tokenisation is requested.

  3. After successful payment initiation, Token generates a tokenised account ID and returns it in the API response.

  4. The merchant can store this tokenised account ID for future use.


Returning Payment

  1. The user returns to the merchant’s site and chooses to pay again.

  2. The merchant initiates a payment request using the previously stored tokenised account ID.

  3. The payment is processed without the need to re-enter or re-select account details.


Supported Scenarios

  • Tokenising account details at payment initiation: When a payment is created with the tokenisation flag, Token generates and returns a tokenised account ID.

  • Tokenising account details from refund information: If account details are returned as part of a refund process, these can also be tokenised and stored.

  • Tokenising account details as a standalone flow: Provide account information for a tokenised ID to be assigned to it outside of a payment flow.

  • Deleting a tokenised account: Merchants can request deletion of a tokenised account, ensuring it is no longer available for future payments.

  • Retrieving a tokenised account: Merchants can retrieve details associated with a tokenised account ID if needed.

  • Initiating payments using a tokenised account: Payments can be initiated using only the tokenised account ID, without exposing sensitive account information.


Key Concepts

  • Tokenised Account ID: A unique identifier generated by Token to represent a specific PSU’s bank account for a given TPP.

  • Account Details: The underlying sensitive information (IBAN, account number, sort code, etc.) which is securely stored and referenced only via the tokenised account ID.

  • PSU Identification Service: The service responsible for managing the mapping between tokenised account IDs and actual account details.


Data Flow

  1. Creation: When a payment initiation request includes the tokenisation flag, Token generates a tokenised account ID and stores the mapping to the actual account details.

    1. A Tokenised account can also be generated outside of a Payment initiation and used in a future payment.

  2. Retrieval: The tokenised account ID can be used in future API calls to reference the account without exposing sensitive data.

  3. Deletion: Tokenised account IDs can be deleted upon request, removing the mapping and ensuring the account can no longer be used via that token.


Security and Compliance

  • Account details are stored securely and encrypted.

  • Tokenised account IDs are unique per TPP and account.

  • The feature is configurable at the TPP level and only activated when explicitly requested.

  • Deletion of tokenised accounts is supported to comply with data privacy regulations.


Example API Usage

Create a Tokenised Account

Endpoint: POST /tokenized-accounts

  • Provide debtor information and receive a tokenizedAccountId

Example Request:

{
  "bankId": "mock-redirect",
  "accountDetails": {
    "name": "John Doe",
    "ultimateName": "John Doe Ltd",
    "iban": "GB61MOCK00000001468953"
  }
}

Create Payment with Tokenisation

Endpoint: POST /v2/payments

  • Include the returnTokenizedAccount=true boolean in the payment initiation request.

Example Request:

{
  "initiation": {
    "flowType": "API_ONLY",
    "bankId": "mock-redirect",
    "refId": "1762517382",
    "remittanceInformationPrimary": "Panini",
    "remittanceInformationSecondary": "RemittanceSecondary1762517382",
    "amount": {
      "value": "1000.00",
      "currency": "GBP"
    },
    "localInstrument": "FASTER_PAYMENTS",
    "returnRefundAccount": true,
    "risk": {
      "contractPresentIndicator": true
    },
    "debtor": {
      "name": "Debs Debtor",
      "sortCode": "123456",
      "accountNumber": "12345678"
    },
    "creditor": {
      "name": "Jimmy",
      "sortCode": "000000",
      "accountNumber": "03503288"
    },
    "callbackUrl": "https://auth.stg.token.io/mock-integration/dumb",
    "callbackState": "CallbackState1762517382",
    "returnTokenizedAccount": true
  },
  "pispConsentAccepted": true
}
  • Receive a tokenizedAccountId in the response within the debtor object.

Initiate Payment with Tokenised Account

Endpoint: POST /v2/payments

  • Provide the tokenizedAccountId in the payment initiation request instead of raw account details.

Example Request:

{
  "initiation": {
    "flowType": "API_ONLY",
    "bankId": "mock-redirect",
    "refId": "1762517382",
    "remittanceInformationPrimary": "Panini",
    "remittanceInformationSecondary": "RemittanceSecondary1762517382",
    "amount": {
      "value": "1000.00",
      "currency": "GBP"
    },
    "localInstrument": "FASTER_PAYMENTS",
    "returnRefundAccount": true,
    "risk": {
      "contractPresentIndicator": true
    },
    "debtor": {
      "tokenizedAccountId": "taixxxxxx"
    },
    "creditor": {
      "name": "Jimmy",
      "sortCode": "000000",
      "accountNumber": "03503288"
    },
    "callbackUrl": "https://auth.stg.token.io/mock-integration/dumb",
    "callbackState": "CallbackState1762517382",
    "returnTokenizedAccount": true
  },
  "pispConsentAccepted": true
}

Get all tokenised Accounts

Endpoint: GET /tokenized-accounts

  • Returns a list of all tokenised accounts for a member

Get a specific tokenised Account

Endpoint: GET /tokenized-accounts/{{tokenised-account-id}}

  • Returns a specific tokenised account

Example response:

{
  "accountDetails": {
    "name": "Default Debtor",
    "iban": "GB61MOCK00000001468953"
  }
}

Delete a Tokenised Account

Endpoint: DELETE /tokenized-accounts

  • Call the delete endpoint with the tokenizedAccountId to remove the mapping.

How can I create an Account on File outside of the payment flow?

In addition to creating an Account on File during a payment, Token also allows you to create a tokenised account as a standalone action - before any payment is made. This is useful if you want to securely store a user’s bank account details for future payments, enabling a seamless “Remember Me” experience.

Scenario

Imagine a user signs up for your service and wants to save their bank account for future purchases. Instead of waiting until their first payment, you can create a tokenised account immediately, so the user won’t need to re-enter their details next time.

  • How it works:

    • Your application collects the user’s bank account details (such as IBAN or account number and sort code).

    • You call the Token API endpoint to create a tokenised account: POST /tokenized-accounts

      • Include the user’s account details in the request.

    • Token returns a tokenizedAccountId in the response.

    • You store this tokenizedAccountId securely and use it for future payments, without needing to handle sensitive account information again.

Example API Request

POST /tokenized-accounts
{
  "bankId": "mock-redirect",
  "accountDetails": {
    "name": "John Doe",
    "ultimateName": "John Doe Ltd",
    "iban": "GB61MOCK00000001468953"
  }
}

Example API Response

{
  "tokenizedAccountId": "tai:36iyGawqeXrzs8LdqocCxVoFrkgA:5zJAqBuv"
}

Benefits

Users can save their account details once and enjoy faster, easier checkouts in the future.

Merchants and TPPs reduce friction and improve conversion rates by offering a “remember me” experience for bank accounts, similar to card-on-file.


If you have any feedback about the developer documentation, please contact devdocs@token.io

Previous page
Next page
© 2025 TOKEN, INC. ALL RIGHTS RESERVED.