Prerequisites
- Account: a virtual account, opened as in Open a Virtual Account.
- API Key: a server API key with the
virtual-accounts.readandvirtual-accounts.updatescopes. In staging, all scopes are included by default.
List Accounts
List the accounts of your project. AdduserLocator to list the accounts of one user.
Response
nextCursor and previousCursor appear only when a page exists in that direction. Send the same filters when you follow a cursor.
Each filter takes up to 20 values and matches any of them. An account is listed when it matches every filter sent. A malformed value, more than 20 values, a
limit outside 1 to 100, or an unknown cursor answers 400 payments:virtual-account.invalid-request.
Change the Wallet or Token
Onlydestination and label can change. Send destination whole, with the same rules as on create. For an EUR account, the token can switch between eurc and usdc, alone or together with the wallet and chain.
destination, label, and updatedAt. The bank details, the account holder, the status, and the statusReason stay as they are.
A change applies to deposits recorded after it. A deposit recorded before the change keeps the wallet, the token, and the rate on its order. When two changes reach the same account, the last to arrive wins, so read the account to confirm its destination.
A change to a different wallet address follows the wallet rules of create: the user proves they control the wallet first, and the wallet is screened. A change that keeps the address, such as a new label or token, needs no new proof.
Fix the request
Wallet checks
Conflicts
Close an Account
Closing is final: nothing reopens a closed account.pending, active, or suspended, and returns it with status closed and statusReason client-closed. On an account that is already closed or failed, it returns 200 with the account unchanged.
- A deposit recorded before the close still finishes: it is delivered, or it goes back to the sender if it fails a check.
- A deposit that arrives after the close is not delivered and goes back to the sender.
- The bank details stay readable on the closed account.
- After a close, the same create call opens a new account with new bank details.
Account Statuses
Every account has astatus and a statusReason. Treat both sets as extensible. See Account Statuses for what each status means and how an account moves between them.
statusReason is null unless the status is one of the three in the table.
When several causes suspend an account,
statusReason shows the one listed first in the table. Once issued, the bank details stay readable in every status and are never given to another user.
Follow Status Changes
Crossmint sends thevirtual_accounts.status.updated webhook each time the status or the statusReason of an account changes. Read the account when it arrives. See Handle Account Status Changes for the payload.
Next Steps
Track Deposits
Follow each bank transfer as an order
Test in Staging
Simulate deposits and force each outcome

