Skip to main content
Each Virtual Account connects local bank account details to a designated blockchain wallet. Once created, the account can be reused to process payments without additional account creation calls. Crossmint manages account issuance, payment processing, compliance checks, and conversion between fiat and stablecoins.

The API Flow

The diagram below illustrates how Virtual Accounts work, using a first-party EUR deposit in the EU as an example. Sequence between the user's bank, your server, Crossmint, and the user's wallet. Open the account, once per account: your server records the legal documents, links the wallet, and calls POST /virtual-accounts, which returns 201 active with the bank details. Each bank transfer starts with the user: a SEPA transfer to the IBAN, then the webhooks orders.quote.created, orders.payment.succeeded, and orders.delivery.initiated, EURC or USDC delivered onchain to the wallet, the webhook orders.delivery.completed, and GET /orders/{orderId} returning the order with the amount delivered

1. Create a Virtual Account

A virtual account only needs to be created once.
  1. Record terms acceptance: The user accepts Crossmint’s terms of service and privacy policy, and your server records their acceptance.
  2. Link a wallet: Specify the destination wallet and provide proof of ownership when required. Crossmint wallets belonging to the user don’t require additional linking.
  3. Create the account: Provide the user’s details, currency, destination wallet, and stablecoin. Crossmint returns the bank account details to display to your user.
See Open a Virtual Account for implementation details.

2. Process Payments

Once the account is active, users can send funds to its bank details. Each incoming transfer creates a separate order. For the illustrated EUR deposit flow:
  1. Payment received: Crossmint detects the incoming transfer, creates an order, and sends orders.quote.created.
  2. Payment verified: Crossmint performs the required checks and sends orders.payment.succeeded when the payment is approved.
  3. Conversion initiated: Funds are converted into the designated stablecoin, the exchange rate is fixed, and Crossmint sends orders.delivery.initiated.
  4. Settlement completed: Stablecoins are delivered to the destination wallet. Once confirmed onchain, Crossmint sends orders.delivery.completed.
  5. Retrieve transaction details: Use the Get Order API to retrieve the final amount delivered.
Each subsequent deposit follows the same process, without requiring a new virtual account.

Account Statuses

Virtual Accounts have five possible statuses: Account statuses: create returns a pending account, which becomes active when the bank details are issued, suspended when a restriction applies as it opens, or failed when it is refused or times out. An active account can be suspended and resumed. Pending, active, and suspended accounts can be closed with DELETE, and the banking partner can close an active or suspended account An account can become active immediately upon creation or transition from pending once bank details are issued. An account may also become suspended due to restrictions and return to active once those restrictions are resolved. Accounts in pending, active, or suspended status can be closed through the API. The banking partner may also close accounts. Every status change triggers a virtual_accounts.status.updated webhook. See Manage Virtual Accounts for additional details.

Payment Reviews and Failures

Each incoming transfer creates an order, including payments that are rejected or returned.
  • Under review: orders.payment.in_review is emitted when a payment requires additional checks. The payment subsequently proceeds or is returned.
  • Rejected: orders.payment.failed is emitted when a payment fails verification. The funds are returned to the sender in full.
  • Completed: Once approved, the payment proceeds through conversion and settlement.
Each deposit is either successfully delivered or returned to the sender, never both. See Deposit States for the complete payment lifecycle.

See Also

REST API Quickstart

Create a virtual account and test a deposit

Track Deposits

Monitor payments and settlement through webhooks