Customer Bank Accounts (AIS)

Retrieve customer bank account information, balances, and transactions using Account Information Services (AIS) powered by Token.io and Open Banking.

Overview

The Customer Bank Accounts API allows you to:

• Access customer bank account details (account numbers, sort codes, IBANs)
• Retrieve real-time account balances
• Fetch transaction history with pagination
• Support affordability checks and proof of wealth verification

How It Works

1. Create Onboard Session - Include AIS options when creating a customer onboard session
2. Customer Authorization - Customer completes the onboard session, authorizes bank access via their banking app
3. Bank Accounts Stored - Selected bank account(s) are stored with access tokens (valid for 90 days)
4. Retrieve Data - Use the bank account endpoints to access balances and transactions

AIS Options

When creating an onboard session, you can specify which bank data to request:

Endpoints

List Customer Bank Accounts

Description: Returns all bank accounts connected by the customer during onboard sessions.

Required Permission: read_customer_bank_accounts

Response:

{
  "accounts": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tokenIoBankAccountId": "acc_xyz123",
      "name": "Main Account",
      "bankName": "Barclays Bank",
      "sortCode": "20-00-00",
      "accountNumber": "12345678",
      "accountHolderName": "John Doe",
      "currency": "GBP",
      "isAccessible": true,
      "created": "2025-10-20T10:30:00Z"
    }
  ]
}

Field Descriptions:

• isAccessible - Whether the access token is still valid (not expired)
• tokenExpiry - When the Token.io access expires (typically 90 days from authorization)
• onboardSessionId - Which onboard session retrieved this account

Get Bank Account Balance

Description: Retrieves the current balance for a specific bank account.

Required Permission: read_customer_bank_account_balances

Response (Success):

{
  "current": 1250.50,
  "available": 1150.00,
  "currency": "GBP",
  "updatedAt": "2025-10-23T09:15:00Z",
  "isExpired": false
}

Response (Token Expired):

{
  "isExpired": true,
  "error": "token_expired",
  "message": "Bank access has expired. Customer needs to re-authorize."
}

Get Bank Account Transactions

Description: Retrieves transaction history for a specific bank account.

Required Permission: read_customer_bank_account_transactions

Query Parameters:

• startDate (optional) - ISO date format (YYYY-MM-DD). Default: 30 days ago
• endDate (optional) - ISO date format (YYYY-MM-DD). Default: today
• continuationToken (optional) - For pagination, from previous response

Response:

{
  "transactions": [
    {
      "id": "tx_abc123",
      "amount": -45.99,
      "currency": "GBP",
      "description": "TESCO STORES",
      "timestamp": "2025-10-22T14:30:00Z",
      "type": "DEBIT",
      "status": "BOOKED"
    },
    {
      "id": "tx_def456",
      "amount": 1500.00,
      "currency": "GBP",
      "description": "Salary Payment",
      "timestamp": "2025-10-20T09:00:00Z",
      "type": "CREDIT",
      "status": "BOOKED"
    }
  ],
  "continuationToken": "offset_xyz789",
  "isExpired": false
}

Token Expiry & Re-authorization

Access tokens retrieved during the onboard session typically expire after 90 days. When tokens expire:

• The isAccessible field on bank accounts becomes false
• Balance and transaction requests return isExpired: true with error details
• Customer must complete a new onboard session to re-authorize bank access

Best Practice: Check the isAccessible field before requesting balances or transactions to avoid unnecessary API calls.

Complete Example

// 1. Create onboard session with AIS
const session = await fetch('/api/onboard/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: 'cust_abc123',
    options: {
      identity: {
        identityCheck: true,
        amlExtensiveScreening: true
      },
      ais: {
        balances: true,
        transactions: true,
        accountLimit: 1  // Require single account
      }
    }
  })
});

// 2. Direct customer to onboardUrl to complete authorization
// ... customer completes flow ...

// 3. Retrieve bank accounts
const accounts = await fetch('/api/customers/cust_abc123/bank-accounts', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

// 4. Get balance for specific account
const balance = await fetch(`/api/customers/cust_abc123/bank-accounts/${accountId}/balance`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

// 5. Retrieve transactions
const transactions = await fetch(
  `/api/customers/cust_abc123/bank-accounts/${accountId}/transactions?startDate=2025-09-01&endDate=2025-10-23`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

Security & Compliance

• Regulatory Compliance: All AIS operations use your merchant's registered sub-TPP credentials
• Customer Consent: Bank access requires explicit customer authorization via their banking app
• Data Privacy: Balance and transaction data is retrieved in real-time from Token.io, not stored by Trustist
• Access Control: API keys must have appropriate permissions for each operation

Common Errors