Customer 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 financial accounts connected through AIS, including deposit accounts, electronic money accounts, cards and credit products where provided by the bank
• 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. Accounts Connected - Trustist records the accounts selected by the customer and their authorised access
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 Accounts

Description: Returns all accounts connected by the customer during onboard sessions. Depending on the bank and AIS provider, these may include current or savings accounts, electronic money accounts, cards, loans, mortgages, or other account products. financialAccountType is Trustist's normalized product classification. The provider's raw type is also retained for compatibility and investigation.

Required Permission: read_customer_bank_accounts

Response:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bankName": "Barclays Bank",
    "accountHolderName": "John Doe",
    "sortCode": "20-00-00",
    "accountNumber": "12345678",
    "iban": "GB33BUKB20201555555555",
    "currency": "GBP",
    "type": "CURRENT_ACCOUNT",
    "financialAccountType": "CurrentAccount",
    "cardLastFour": null
  }
]

A card account can be returned with financialAccountType such as CreditCard and a cardLastFour value, without a sort code, account number or IBAN. The card number itself is not returned. accountNumber refers only to the account number for domestic bank-account routing; it is not a card number. Other products may also have no domestic or international payment-routing fields.

Field Descriptions:

• id - Trustist's bank-account identifier; use it for balance and transaction requests
• financialAccountType - Trustist's normalized product classification: Unknown, Other, CurrentAccount, Savings, ElectronicMoney, CashAccount, Card, CreditCard, ChargeCard, PrepaidCard, Loan, Mortgage, SalaryAccount, TransactionAccount, LimitedLiquiditySavings, MoneyMarket, or Overdraft. Broad CashAccount is not proof that an account can receive payments. Restricted savings, money-market and overdraft accounts are not payment destinations. Personal/business ownership is not modeled in this field.
• type - Provider's raw account type, retained for compatibility and investigation
• cardLastFour - Last four card digits when the provider supplies them
• bankName, accountHolderName, sortCode, accountNumber, iban, and currency - Details supplied for the connected account; routing fields may be absent for cards or other account types

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",
  "retrievedAt": "2025-10-23T09:15:00Z",
  "isExpired": false
}

retrievedAt is the UTC time at which Trustist successfully retrieved the balance. Banks do not consistently provide a separate timestamp for when their ledger balance was last updated.

Response (Token Expired):

{
  "isExpired": true,
  "error": "access_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). Defaults to UTC today minus 30 days; explicit dates are recommended for predictable history windows.
• endDate (optional) - ISO date format (YYYY-MM-DD). Defaults to UTC today; explicit dates are recommended for predictable history windows.
• continuationToken (optional) - The offset returned by the previous response; pass it through unchanged for the next page.

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"
    }
  ],
  "offset": "offset_xyz789",
  "isExpired": false
}

Use the provider-returned offset value as the next continuationToken when paginating. Stop when no offset is returned. If isExpired is true or error is access_expired, stop and ask the customer to re-authorize; do not blindly retry. The terminal access_denied error means the unchanged request must not be retried; try a supported recent date range or re-authorize.

Response (Bank or provider denied this request):

{
  "transactions": [],
  "offset": null,
  "isExpired": false,
  "error": "access_denied",
  "message": "The bank did not permit access to these transactions. The requested period may be unavailable; do not retry the same request. Re-authorize AIS access if the problem persists."
}

For compatibility, AIS access errors are returned in the response model. Always inspect error before following offset. Retry transient retrieval_failed responses with normal backoff, but do not retry access_denied without changing the request or re-authorising.

Set Default Payout Bank Account

Description: Sets the default payout bank account for the customer.

Required Permission: read_customer_bank_accounts

Request Body:

{
  "bankAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response:

{
  "defaultPayoutBankAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Delete (Archive) Customer Bank Account

Description: Archives a customer bank account (soft delete).

Required Permission: read_customer_bank_accounts

Response:

{
  "defaultPayoutBankAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Delete (Archive) All Customer Bank Accounts

Description: Archives every active bank account for the customer in one request. The customer record remains active. Trustist clears its default payout bank-account selection. An in-progress account selection remains available; it can connect accounts after the archive.

Optional Query Parameter: orgId identifies the tenant customer organisation, following the same lookup rules as other customer bank-account operations.

Authentication: Use an authenticated API client and an authorised merchant context for the tenant. When the tenant has multiple merchants, provide X-Trustist-MerchantId.

Response: Returns the customer's remaining default payout account ID; this is null after the bulk archive.

{
  "defaultPayoutBankAccountId": null
}

Trustist cancels each distinct AIS consent used by the customer's stored active accounts before saving the archive, except a consent still used by an in-progress account selection. If a consent cancellation fails, the request fails and the local accounts remain active. Provider cancellation and the local database write cannot be one atomic operation: a later cancellation or database conflict can fail after an earlier consent was already cancelled. Retry the request after a failure; completed provider cancellations are safe to repeat. An empty account list succeeds, so the call can also be used to ensure there are no active bank accounts.

Failure responses: 502 consent_cancellation_failed means an AIS consent could not be cancelled; retry the request after addressing the provider failure. 409 customer_modified means the customer changed during the archive; retry the request. Other failures return an error response and never indicate successful archival.

Access Expiry & Re-authorisation

AIS access expires at the time returned by the provider. Trustist checks access when a balance or transaction request is made. When access has expired:

• Balance and transaction responses return isExpired: true with error: "access_expired"
• Transaction responses may return error: "access_denied" with isExpired: false; stop and do not retry the unchanged range
• The customer must complete a new AIS authorisation to restore access

The bank-account list intentionally does not expose provider tokens, expiry metadata, customer IP data, or other internal AIS fields.

Complete Example

// 1. Create onboard session with AIS
const session = await fetch('/v1/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('/v1/customers/cust_abc123/bank-accounts', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

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

// 5. Retrieve transactions
const transactions = await fetch(
  `/v1/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: AIS access is provided through Trustist's configured Open Banking service
• 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