Cookbook
Open a bank account
Sub-agent opens a corporate bank account on a partner onboarding portal. The customer never sees a redirect.
Last updated
Sub-agent opens a corporate bank account on a partner onboarding portal. The customer never sees a redirect.
Trigger
An entity has its EIN and is ready to bank.
Call sequence
1. Initiate
POST /v1/bank_accounts/initiate { entity, partner: 'mercury' }2. Watch the sub-agent session
// bank_account.opened lands when fundedIdempotency
Initiation idempotent on `(entity, partner)`.
Webhooks
| Event | Description |
|---|---|
sub_agent_session.completed | Onboarding finished. |
bank_account.opened | Account is live. |
Errors
| Status | Code | Description |
|---|---|---|
422 | ein_pending | EIN not yet issued. |
KYB flow
The KYB cascade pre-fills entity name, EIN, formation state, and beneficial owners from existing Matter resources — no re-keying.
Webhook events:
| Event | Action |
|---|---|
bank_account.evidence_requested | Partner bank wants more evidence (a stakeholder's ID, an updated formation document). Surface to the founder; upload via addStakeholderEvidence or the entity-evidence endpoint. |
bank_account.activated | Account is active — routing number + masked account number now populated. Ready to receive incoming transfers. |
bank_account.frozen | Compliance hold (sanctions match, etc.). Investigate via the partner-bank dashboard. |
KYB typically completes same-day for clean entities; longer if evidence
is requested. In test mode, X-Matter-Test-Speed: instant activates
the account immediately.
Account details
GET /v1/entities/{entity_id}/bank_accounts/{bank_account_id}Look for status: "active", routing_number: "<9 digits>", and
account_number_last_4: "<4 digits>". The full account number is not
returned via API for security; retrieve from the partner-bank dashboard
SSO link in the Matter dashboard.
Common gotchas
- Tier-4 token required.
createBankAccountandcreateTransferboth require tier-4 because they are KYB-triggering / money-moving. Tier-3 tokens get403 insufficient_tier. - Beneficial-owner evidence. If a Stakeholder lacks an identity document, the partner bank will request it before activating. Pre-load evidence on Stakeholders ahead of opening the account to avoid the back-and-forth.
- Operating vs reserve accounts. The
nicknameis for the dashboard only; multiple accounts can be opened on the same entity for operational segregation (e.g., "Operating" + "Tax Reserve").
See the Banking landing page for the full operation list.