> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md
# Bank account change lifecycle
> Understand how a paypoint's bank account change moves from request to completion
Bank account change access requires configuration by the Payabli team. Contact us to get started.
A bank account change updates the deposit or settlement account tied to a paypoint. Because it moves where a merchant's money goes, it isn't a direct field update. Payabli models each request as a case that moves through a defined lifecycle. You submit it, Payabli verifies the account, a reviewer checks it when needed, and the switch completes after approval.
This guide covers the shared concepts: the partner roles, the case states, how verification works, and why account and routing numbers are never returned. For the request and response details of each endpoint, see the [Case Management API reference](/developers/api-reference/bankChanges/create-bank-account-change). To submit one step by step, see [Submit a bank account change](/guides/pay-ops-developer-bank-account-change-submit).
## Who can do what
Two kinds of partners work with bank account changes, and each can do different things with a case.
| Capability | Platform Partner | Enterprise Partner |
| ----------------------------------------- | ---------------- | ------------------ |
| Validate and submit a change | Yes | Yes |
| View and track case status | Yes | Yes |
| Add notes to a case | Yes | Yes |
| Assign, escalate, approve, or deny a case | No | Yes |
**Platform Partners** submit bank account changes and track their status, but they don't make the risk decision. That decision stays with Payabli. When a case needs review, a Platform Partner watches its status and adds notes, and sees the case move to `Approved` or `Denied` once Payabli decides.
**Enterprise Partners** manage their own risk review. They can do everything a Platform Partner can, and they can also action a case: assign it to a reviewer, escalate it, and approve or deny it.
If you're not sure which type your organization is, contact the Payabli team.
These permissions apply on both surfaces: the Case Management API and the Payabli Portal. A Platform Partner sees a case's status in the Portal but not the actions to approve or deny it.
## The bank account change lifecycle
Each case moves through a defined set of states. Most requests follow the same path: from `Submitted`, through automatic verification, to `Completed`. A case only needs a person when verification is inconclusive.
| State | What it means | Typical duration |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Submitted | The case is created and verification is about to start. | Seconds |
| Verifying | Automatic bank account verification is running. | Seconds to minutes |
| PendingReview | Verification was inconclusive, so a reviewer needs to decide. | Until reviewed |
| Assigned | A reviewer owns the case. | Until reviewed |
| PendingResponse | The case is waiting on more information, such as from the merchant. | Varies |
| Escalated | The case goes to senior review. | Varies |
| Approved / AutoApproved | The change has cleared and the switch is about to start. `AutoApproved` means verification passed cleanly with no reviewer. | Seconds |
| PendingCompletion | The account switch is running and awaiting processor confirmation. | Under a minute |
| Completed | The new account is live and funding has resumed. | Final |
| Denied | The request was rejected. | Final |
| Error | Something failed during the switch. Funding resumes automatically, and a reviewer can recover the case. See [How review works](#how-review-works). | Until resolved |
`Completed` and `Denied` are terminal states with no further transitions.
Diagram: Bank account change case lifecycle
The diagram shows the main flow of a bank account change case:
* A **Submitted** case moves to **Verifying** when background verification starts.
* From **Verifying**, a case can go to **AutoApproved** (verification passed cleanly), **PendingReview** (verification was inconclusive), or **Denied** (verification failed).
* A reviewer moves a **PendingReview** case to **Approved** or **Denied**.
* **Approved** and **AutoApproved** cases move to **PendingCompletion**, where the account switch runs, and then to **Completed**.
* **Completed** and **Denied** are final states.
The review sub-states and the Error state aren't shown here — see the state table above for the full set.
## Timing expectations
Bank account changes are asynchronous. You submit a case, background jobs move it forward, and you check status by fetching the case.
* **Verifying** typically resolves in seconds to minutes.
* **PendingCompletion** typically resolves in under a minute, but it can take longer while the processor confirms the switch. A case that stays in `PendingCompletion` for more than an hour is a signal to contact Payabli, not a sign that you need to resubmit.
Because the flow is asynchronous, poll the case to track its status rather than expecting an immediate final result from the submit call.
## Scheduling a change
By default, a change runs as soon as it's approved. To run it later, set a `scheduleFor` time when you create the case. Payabli still verifies and reviews the case right away, then holds it in `Approved` or `AutoApproved` until the scheduled time, when the switch runs. A scheduled time must be between 1 hour and 30 days in the future, in UTC.
## Why account and routing numbers aren't returned
When you submit a bank account change, Payabli validates the account and routing numbers, then tokenizes them. The raw numbers are write-only: they're never stored in the case and never returned in any response. A case's parameters include a `bankToken` that references the vaulted account, plus non-sensitive details like the bank name and account type. They never include the account or routing numbers themselves.
This keeps sensitive bank details out of every read path, including case lists, case details, and notes. If you need to confirm which account a case points to, use the nickname and bank name you submitted rather than the account number.
## How verification works
After you submit a case, Payabli runs automatic bank account verification before any money moves. Verification checks that the account exists, is open, and belongs to the expected holder.
Verification produces one of three outcomes:
* **AutoApproved** — the account passed cleanly, so no reviewer needs to step in.
* **PendingReview** — the result was inconclusive, so a reviewer decides. Only Enterprise Partners can act on these.
* **Denied** — the account failed verification. This is final.
Once verification finishes, the result appears in the case's `metadata.verification` field as a set of result codes with a code, a name, and a description. This field is empty until verification completes.
## How review works
When verification is inconclusive, a case moves to `PendingReview` and waits for a person to decide. Only Enterprise Partners act on these cases. For Platform Partners, Payabli makes the decision.
Before deciding, a reviewer can move a case through a few working states:
* **Assigned** — a reviewer takes ownership of the case.
* **PendingResponse** — the reviewer needs more information, such as from the merchant, and holds the case until it arrives.
* **Escalated** — the reviewer raises the case for senior review.
From any of these states, the case moves to `Approved` or `Denied`. If the account switch later fails, the case moves to `Error`. Funding resumes automatically, and a reviewer can recover the case back to review, approval, or denial.
## Related resources
See these related resources to help you get the most out of Payabli.
#### References
* **[Case Management API reference](/developers/api-reference/bankChanges/create-bank-account-change)** - Request and response details for each bank-account-change endpoint
#### Related topics
* **[Submit a bank account change with the API](/guides/pay-ops-developer-bank-account-change-submit)** - Submit and track a bank account change with the Case Management API
* **[Manage bank account changes (Portal)](/guides/pay-ops-portal-bank-account-changes-manage)** - Manage bank account changes from the hosted Bank Changes queue