Submit a bank account change with the API
This guide walks through submitting a bank account change with the Case Management API: validate the account, create the case, and track it as verification runs. For the states a case moves through and who can act on it, see Bank account change lifecycle.
Prerequisites
Before you start, make sure you have:
- Case Management access enabled for your organization. Contact the Payabli team if you’re not sure.
- An OAuth Bearer token. These endpoints authenticate with a Bearer token, not the
requestTokenAPI key. See OAuth authentication. - The numeric ID of the paypoint whose account you’re changing.
The examples use the sandbox base URL, https://api-sandbox.payabli.com/api. Switch to https://api.payabli.com/api for production.
Steps
These steps take you from validating the account through to a completed change.
Validate the request
Before you create a case, validate the account details. Validation runs the same checks as creation without saving anything, so you can catch problems first.
The response tells you whether the request is valid:
Resolve any blockingConditions before you continue. warnings are informational, so you can create the case with them present.
Create the case
Once validation passes, create the case. Add a nickname, a bankName, and default to the same details you validated. Payabli tokenizes the account and takes the account holder name from the paypoint’s legal name.
To run the change later instead of right after approval, add a scheduleFor UTC timestamp between 1 hour and 30 days out. Payabli verifies and reviews the case right away, then waits until that time to complete the switch.
A 201 response returns the full case in the Submitted state. Save the uuid — you’ll use it to track the case. The raw account and routing numbers aren’t returned; the case carries a bankToken instead.
Track verification
After creation, the case moves to Verifying on its own and automatic verification runs. Fetch the case to check its status.
Verification resolves to one of three states:
AutoApproved— the account passed cleanly and moves toward completion.PendingReview— the result was inconclusive and needs a reviewer.Denied— the account failed verification. This is final.
The outcome appears in metadata.verification once verification finishes:
Poll the case rather than waiting on the create call, since the flow is asynchronous.
Review the case (Enterprise Partners)
If a case is PendingReview, an Enterprise Partner acts on it. Platform Partners skip this step — Payabli makes the decision, and the case moves to Approved or Denied on its own.
First check which actions are available:
Assign the case to a reviewer with the assign endpoint:
Approve or deny the case with the transitions endpoint. Include a declineReason when you deny.
A successful call returns the updated case with its new state and a new stateHistory entry recording the action.
Firing an action that isn’t valid for the case’s current state returns a 409. Use the transitions list to confirm what’s allowed first.
Confirm completion
An approved case moves to PendingCompletion while the account switch runs, then to Completed when the processor confirms it. Fetch the case one more time to confirm it reached Completed.
PendingCompletion typically clears in under a minute. If a case stays there for more than an hour, contact the Payabli team rather than resubmitting.
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