Skip to main content

​
Overview

An organization can be paid into an account registered in Tesouro through Embedded Banking, or into an account that Tesouro only holds the details of.
  • Accounts registered through Embedded Banking come in two kinds: internal bank accounts, held at Tesouro’s sponsor bank, and external bank accounts, which live at the organization’s outside bank and are linked and verified before they can receive funds. To learn about both, see Bank accounts in the Embedded Banking guides.
  • Bank details are records that hold US account information and nothing else. Use them when an organization needs its payment details printed on a document without registering an account in Tesouro. Tesouro stores and renders them, but doesn’t hold the funds and doesn’t verify the account.
This page covers bank details records. To learn how an invoice or a quote points at any of the three, see Bank account in the invoice creation guide.
Counterpart bank accounts are a different resource, documented in Counterpart bank accounts. They describe who an organization pays rather than who pays the organization, and they accept non-US account information such as iban and sort_code.

​
Add a bank details record

To add a bank details record to an organization, call POST /bank-details with account_holder_name, account_number, and routing_number. Optionally add bank_name and display_name. Sample request:
The successful response returns the unique id assigned to the record, along with other details:
Use that id on an invoice or a quote with "bank_account_type": "BANK_DETAILS".

​
List all bank details records

To get all bank details records of an organization, call GET /bank-details. The response returns every record the caller can see, in one page.

​
Retrieve a bank details record

To get a single record, call GET /bank-details/{bank_account_id}.

​
Edit a bank details record

You can change display_name and account_holder_name. Call PATCH /bank-details/{bank_account_id} with the new values. Fields you omit keep their current value. bank_name, account_number, and routing_number are set when the record is created and can’t be changed. To correct one of them, create a new record and reference it on future documents.
account_holder_name is required, so it can’t be cleared. Sending it as null returns 409, and sending an empty string returns 422.

​
Delete a bank details record

To delete a record, call DELETE /bank-details/{bank_account_id}. Deleted records stop appearing in the list and return 404 on subsequent requests. Documents that already reference a deleted record keep rendering their copy of the payment details. New documents can’t reference it: attaching one returns 409.

​
Set a default bank account

An organization can nominate one default bank account of any of the three kinds, stored in its settings as defaultBankAccount:
To clear it, send "defaultBankAccount": null explicitly. Omitting the field leaves the current value alone. The default is a hint for your own interface to preselect an account. Tesouro doesn’t apply it to documents automatically: an invoice created without bank_account_id has no bank account. Tesouro also doesn’t check that the account exists, so validate the pair before saving it. Setting the default is an organization setting, so it requires the organization_settings:write:org scope rather than a bank account permission.

​
Where to next

Use a bank account on an invoice

How an invoice points at an internal, external, or bank details account.

Internal and external bank accounts

How accounts registered through Embedded Banking are created and what state they reach.