Skip to main content
This guide covers what you do with a virtual account after it opens: list accounts, change where deposits go, close an account, and read or react to its status. Every call returns the account object of Open a Virtual Account.

Prerequisites

  • Account: a virtual account, opened as in Open a Virtual Account.
  • API Key: a server API key with the virtual-accounts.read and virtual-accounts.update scopes. In staging, all scopes are included by default.

List Accounts

List the accounts of your project. Add userLocator 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

Only destination 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.
The response is the account with its new 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.
The call closes an account that is 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 a status 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 the virtual_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