Bank account change lifecycle
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. To submit one step by step, see Submit a bank account change.
Who can do what
Two kinds of partners work with bank account changes, and each can do different things with a case.
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.
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.
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
PendingCompletionfor 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 - Request and response details for each bank-account-change endpoint