---
title: "Create a Payee Bank Account"
method: POST
path: "/payables/payer_accounts/{payer_id}/bank_accounts"
tags: ["Payee Bank Accounts"]
---

# Create a Payee Bank Account

`POST /payables/payer_accounts/{payer_id}/bank_accounts`

## Request

- Base URL: `https://api.justifi.ai/v1`
- URL: `https://api.justifi.ai/v1/payables/payer_accounts/{payer_id}/bank_accounts`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/justifi/apis/justifi-api-documentation/docs/payables/payer_accounts/:payer_id/bank_accounts/post.ts> (a function with typed inputs; its response is checked against the schema)

Register a **receiving** bank account for a payee under this payer account (the account a payment is
paid to). The `account_number` is write-only — it is accepted here but never returned; responses
expose only `account_number_last4`.

**Funding accounts cannot be created here.** The payer account's own funding account — the one
payments are pulled from — is set during provisioning and replaced by JustiFi rather than through this
API, because it decides where money is taken from. This endpoint creates payee receiving accounts only,
and they are created `not_required`: Payables does not validate payee accounts. You can still
*read* funding accounts through `ListBankAccounts` and `GetBankAccount`.

In this version an owner has a single active bank account — creating one for a payee that already has
an active account supersedes the previous one.

**The payer account must be `active` and the payee must not be archived.** Either one is a `400`: a
payer account that is not active registers nothing, and an archived payee can never be paid, so it
has nothing to be paid to.

**A `disabled` payee may still register an account, and doing so returns it to `active`.** That is
the way back for a payee Payables disabled because its bank refused the credit or corrected the
account without saying what to: register the corrected numbers and the payee is payable again,
along with any payment still held for it.

## Path parameters

- `payer_id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `account_holder_name` string, required
  - `routing_number` string, required
  - `account_number` string, required: the full account number; write-only, never returned
  - `account_type` 'checking' | 'savings', required
  - `payee_id` string, required: the payee this receiving account belongs to. The payee must be scoped to the payer account in the path.

## Response `201`

Bank account was created successfully

- object: the standard JustiFi response envelope for a single record
  - `id` string, required: the object id, also found in the data object
  - `type` string, required: the object type
  - `data` object, required: A bank account used for Payables money movement. Exactly one of `payer_account_id` or `payee_id` is set: the former for a funding account (the principal is pulled from it), the latter for a payee's receiving account (the principal is paid to it). Account numbers are write-only — accepted on create, never returned; responses expose only the last four digits. Bank accounts are immutable: to correct details (e.g. after a NOC), a new record is created rather than edited in place. **Which record is active is determined by the owner**, via `payer_account.funding_bank_account_id` or `payee.receiving_bank_account_id` — so registering a new account and pointing the owner at it supersedes the previous one. Listing an owner's bank accounts by `created_at` therefore gives its full account history.
    - `id` string: unique bank account id
    - `type` string: the object type, matching the enclosing envelope's `type`
    - `payer_account_id` string, nullable: the payer account that owns this bank account, when it is a **funding** account. Null on a payee's receiving account. Exactly one of `payer_account_id` and `payee_id` is non-null.
    - `account_holder_name` string: the name on the bank account
    - `routing_number` string: the 9-digit ABA routing number
    - `account_number_last4` string: the last four digits of the account number (the full number is never returned)
    - `account_type` 'checking' | 'savings': the type of bank account
    - `payee_id` string, nullable: the payee that owns this bank account, when it is a **receiving** account. Null on a payer's funding account. Exactly one of `payer_account_id` and `payee_id` is non-null.
    - `verification_status` 'not_required' | 'pending' | 'verified' | 'failed': the state of bank account verification. Read together with which owner field is set, this is the model's signal for how the account is handled: - `not_required` — a payee (receiving) account. Payables does not verify payee accounts; payments are sent without upfront validation, and a bad account surfaces as a returned credit. This is a settled state rather than a "not yet verified" one. - `pending` — a payer (funding) account whose validation is in progress. Payer funding accounts are validated in-app (e.g. during portal funding setup). - `verified` — a payer funding account that has been validated; only a `verified` funding account may fund a payment. - `failed` — validation of a payer funding account failed; it cannot fund payments.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `page_info` unknown, required

## Other responses

- `400`: The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute.
- `401`: The access token is missing, expired, or invalid.
- `403`: The credentials are valid but not permitted to access this resource.
- `404`: No resource exists for the given id (within the scoped payer account).
- `422`: The request was well-formed and passed field validation, but a business rule rejected it — for example a payer funding account that is not `verified`, or a payee with no receiving bank account to credit. Field-level validation failures return `400`, not this. `error.details` carries per-attribute messages where the rule is attributable to one.
- `429`: The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header.

---

[API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)