A bank account is the account a business uses to receive settled funds, pay fees, or both. A single account can serve more than one purpose. Bank accounts are held on the business, not on a location: every location settles through the business's accounts. For the full field list, jump to the Request reference.

Common use cases

• Attach a funding account where settled funds land.
• Add a separate billing account for fees.
• Retire an old account and add a new one.

🚧

PENDING-PUBLISH

The boarding API Reference is pending publication; the ref: targets on this page are placeholders. Replace each with the real boarding-spec operationId once the boarding reference ships.

Scenarios

A bank account is written in full and read back masked. You send the real accountNumber and routingNumber on create; on read, PCE returns only accountNumberLast4 and omits the routing number entirely.

Before you begin (all scenarios)

• You have the businessId the account belongs to.
• You know the account's purpose (funding, billing, or others) and accountType.
• You have the full account and routing numbers to send on create.

Scenario 1: Add a bank account

Attach the account a business settles through. Make a POST request to /v1/businesses/{businessId}/bank-accounts.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/bank-accounts \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": ["billing"],
    "accountNumber": "9988776655",
    "routingNumber": "111000025",
    "accountType": "checking",
    "bankName": "Bank of America",
    "isPrimary": false,
    "externalId": "acme-billing-1"
  }'

Response: 201 Created

{
  "id": "ba_89",
  "uri": "/v1/businesses/{businessId}/bank-accounts/ba_89",
  "externalId": "acme-billing-1",
  "purpose": ["billing"],
  "accountNumberLast4": "6655",
  "accountType": "checking",
  "bankName": "Bank of America",
  "isPrimary": false,
  "createdAt": "2026-06-15T12:10:00Z"
}

accountNumber is written in full and read back masked to accountNumberLast4, so you never get the full number back. routingNumber is not returned on read. accountNumber and routingNumber are not editable: to change them, add a new account and retire the old one (Scenario 2).

Scenario 2: Replace an account

Because the account and routing numbers can't be edited, replacing an account is two steps: add the new one, then retire the old one. Add the replacement first so the business is never without a funding account.

# 1. Add the new account
curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/bank-accounts \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "purpose": ["funding"], "accountNumber": "5566778899", "routingNumber": "021000021", "accountType": "checking", "bankName": "Wells Fargo", "isPrimary": true }'

# 2. Retire the old account
curl -X DELETE https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/bank-accounts/{bankAccountId} \
  -H "x-api-key: <your-key>"

Manage bank accounts

• List or read one: GET /v1/businesses/{businessId}/bank-accounts, or GET /v1/businesses/{businessId}/bank-accounts/{bankAccountId} for one account, in the masked shape above.
• Update: PATCH /v1/businesses/{businessId}/bank-accounts/{bankAccountId} changes purpose, isPrimary, accountType, or bankName only.
• Remove: DELETE /v1/businesses/{businessId}/bank-accounts/{bankAccountId} retires the instrument.

Re-read the account to see changes; there is no status webhook.

🚧

PENDING-PUBLISH

Two things to confirm before publish: (1) no worked GET example for a bank account exists in the source; the masked shape above reuses the create response, which is reasonable given masking is the stated convention but isn't a confirmed GET; (2) whether a retired account stays visible on the business for records and audit.

Request reference

Statuses

A bank account is attached to the business and does not run its own underwriting lifecycle; it is validated as part of the business's requirements. If an account is missing or malformed, it surfaces on the service's missingFields or errors. See Status lifecycle and Underwriting exceptions.

Sandbox testing

Use the sandbox to attach and read accounts before going live, and confirm the masked read shape.

🚧

PENDING-PUBLISH

Sandbox test routing/account numbers are pending the boarding sandbox guide. Confirm before publish.

Go live

The shared pre-production checklist is in Getting Started. Specific to bank accounts:

• A funding account is attached with purpose including funding.
• Account and routing numbers are correct (they can't be edited after create).
• The primary account is the one you want settlements to land in.

Best practices

Next steps

See also

• Create a business: add bank accounts inline in the composite create
• Businesses: how bank accounts fit the entity model
• Underwriting exceptions: resolve a rejected bank account