Bank Account

A Bank Account represents a financial account that can be used for sending and receiving payments. Bank accounts can belong to entities or recipients and include routing details, account details, and payment profiles.

Bank Account Object

{
  "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8y",
  "currency": "USD",
  "current_balance": "1250.75",
  "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
  "owner_type": "Entity",
  "last_synced_at": "2025-01-17T10:30:00Z",
  "party_address": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-17T10:30:00Z",
  "account_details": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9BY2NvdW50RGV0YWlsLzE",
      "account_number_mask": "************0000",
      "account_number_type": "other",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "routing_details": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9Sb3V0aW5nRGV0YWlsLzE",
      "bank_name": "Chase Bank",
      "routing_number": "011401533",
      "routing_number_type": "aba",
      "payment_method": "ach",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "payment_profiles": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
      "status": "active",
      "currency": "USD",
      "payment_method": "ach",
      "usage_type": "debit",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the bank account
`currency`	string	ISO 4217 three-letter currency code (e.g., "USD", "EUR")
`current_balance`	string	Current balance amount as a decimal string
`owner_id`	string	ID of the owner (Entity or Counterparty)
`owner_type`	string	Type of owner: `Entity` or `Counterparty`
`last_synced_at`	string/null	ISO 8601 timestamp of last balance sync, or `null` if never synced
`party_address`	string/null	Address associated with the account holder
`created_at`	string	ISO 8601 timestamp when the account was created
`updated_at`	string	ISO 8601 timestamp when the account was last updated
`account_details`	array	Array of account detail objects containing account number information
`routing_details`	array	Array of routing detail objects containing bank routing information
`payment_profiles`	array	Array of payment profile objects for sending/receiving payments (see Payment Profile)

Nested Objects

Account Details

Account details contain information about the account number.

Attribute	Type	Description
`id`	string	Unique identifier for the account detail
`account_number_mask`	string	Masked account number for security (e.g., "**0000")
`account_number_type`	string	Type of account number: `other`, `iban`
`created_at`	string	ISO 8601 timestamp when the detail was created
`updated_at`	string	ISO 8601 timestamp when the detail was last updated

Routing Details

Routing details define how the bank account can send and receive payments.

Attribute	Type	Description
`id`	string	Unique identifier for the routing detail
`bank_name`	string/null	Name of the financial institution
`routing_number`	string	Bank routing number (format depends on type)
`routing_number_type`	string	Type of routing number (see Routing Number Types)
`payment_method`	string	Payment method supported by this routing detail (see Payment Methods)
`created_at`	string	ISO 8601 timestamp when created
`updated_at`	string	ISO 8601 timestamp when last updated

Routing Number Types

Different regions and payment methods use different routing number formats:

Type	Description	Region/Network	Notes
`aba`	ABA routing number	United States	9-digit code for US banks
`swift`	SWIFT/BIC code	International	International bank identifier
`bsb`	BSB (Bank-State-Branch) code	Australia	6-digit code for Australian banks
`sort_code`	Sort code	United Kingdom	6-digit code for UK banks
`transit_number`	Transit number	Canada	5-digit code identifying bank branch
`institution_number`	Institution number	Canada	3-digit code identifying financial institution
`branch_code`	Branch code	Various countries	Bank branch identifier
`bank_code`	Bank code	Various countries	Bank identifier code
`routing_number`	Generic routing number	Various countries	General purpose routing identifier
`cnaps`	CNAPS code	China	China National Advanced Payment System code
`bpay_biller_code`	BPAY biller code	Australia	Australian bill payment identifier
`biller_id`	Biller ID	Various countries	Generic biller identifier
`email_address`	Email address	Various (e.g., Interac)	Used for email-based transfers

Owner Types

Bank accounts can belong to different types of owners:

Owner Type	Description
`Entity`	Bank account belongs to an entity in your company
`Counterparty`	Bank account belongs to a recipient/counterparty

Available Operations

List Bank Accounts - Returns all bank accounts for a specific company
Get Bank Account - Retrieve details of a specific bank account by ID

Read-Only Access

Bank account information is read-only via the API. Bank accounts are created through:

Multi-currency account enablement (for entities)
Recipient onboarding via hosted pages (for counterparties)
Direct integration with financial institutions

Usage Notes

Masked Data - Sensitive information like full account numbers are masked for security
Balance Accuracy - Balances reflect the most recent sync with financial institutions
Multiple Routing Details - A single bank account may have multiple routing details to support different payment methods
Payment Profiles - For information about payment profiles associated with bank accounts, see Payment Profile

Webhook Notifications

TreasuryPath sends webhook notifications when bank account events occur. Subscribe to these events to receive real-time updates about bank account changes.

Available Bank Account Events

Event Name	Description	Trigger
`BankAccountEvents::CreatedEvent`	Triggered when a bank account is created	A new bank account is added to the system
`BankAccountEvents::UpdatedEvent`	Triggered when a bank account is updated	Bank account details are modified
`BankAccountEvents::DeletedEvent`	Triggered when a bank account is deleted	A bank account is removed

Webhook Payload

All bank account webhooks follow the standard TreasuryPath webhook payload format:

{
  "event": "BankAccountEvents::CreatedEvent",
  "timestamp": "2025-01-17T14:30:00.000Z",
  "company_id": "Z2lkOi8vYXBwL0NvbXBhbnkvMTIz",
  "resource_id": "Z2lkOi8vYXBwL0JhbmtBY2NvdW50LzQ1Ng",
  "actor_id": null
}

Payload Fields

Field	Type	Description
`event`	string	Event type identifier (e.g., `BankAccountEvents::CreatedEvent`)
`timestamp`	string	ISO 8601 timestamp when the event occurred
`company_id`	string	ID of the company that owns the bank account
`resource_id`	string	ID of the bank account that triggered the event
`actor_id`	string/null	ID of the user or API credential that triggered the action, or `null` for system-triggered events

Handling Webhook Events

Scenario 1: Bank Account Created

Sent when a new bank account is added (e.g., through multi-currency account enablement or recipient onboarding).

Webhook payload includes: "event": "BankAccountEvents::CreatedEvent"

Recommended action:

Fetch the full bank account details using GET /api/v1/bank_accounts/{resource_id}
Update your local database with the new bank account
Notify relevant users about the new account

Scenario 2: Bank Account Updated

Sent when bank account information changes.

Webhook payload includes: "event": "BankAccountEvents::UpdatedEvent"

Recommended action:

Fetch the updated bank account details
Sync the changes to your system

Scenario 3: Bank Account Deleted

Sent when a bank account is removed.

Webhook payload includes: "event": "BankAccountEvents::DeletedEvent"

Recommended action:

Mark the bank account as deleted in your system
Stop attempting to use this account for payments
Notify users who had access to this account

Payment Profile Events

Bank accounts have associated payment profiles that enable payment capabilities. When payment profile events occur, webhooks are also triggered. For details about payment profile webhook events, see Payment Profile.

Fetching Full Bank Account Details

Webhook payloads contain minimal information. To get complete bank account details after receiving a webhook:

GET /api/v1/companies/{company_id}/bank_accounts/{resource_id}

The response includes the full bank account object with all nested details (account details, routing details, payment profiles, etc.).

Webhook Best Practices

Always Fetch Full Details - Webhook payloads are intentionally minimal. Always fetch the complete resource details using the API
Handle Idempotency - Use the combination of event + resource_id + timestamp to detect duplicate webhooks
Respond Quickly - Return a 200 OK response within 30 seconds
Verify Signatures - Always verify the TreasuryPath-Signature header to ensure webhook authenticity

For webhook setup, security, and signature verification, see Webhooks.

For detailed API endpoints and request/response examples, see the Bank Accounts API Reference.