Virtual Accounts

Virtual accounts give customers dedicated bank details for receiving funds. Use them when your product needs customer-facing account details or cleaner account-level reconciliation.

Virtual Account Workflow

Integration Flow

1. Create and verify the customer.
2. Request a named rail when needed.
3. Create a Swipelux custodial wallet for the destination stablecoin balance.
4. Create a virtual bank account with a target wallet.
5. Show the account details to the customer.
6. Track incoming funds through transfers and webhooks.

Virtual account creation requires the relevant named rail to be ready_to_use. If the rail is missing or still under review, POST /v1/customers/{customerId}/accounts returns 409 rail_not_ready with requiredRails, requestRailEndpoint, and nextAction.

The target wallet for a virtual account must be a Swipelux-created custodial wallet. Do not use an imported external wallet as the destination for fiat funds arriving through virtual bank account details. If the customer ultimately wants funds in an external wallet, receive the bank transfer into the custodial wallet first, then move funds onward through the supported transfer or payout flow.

When incoming funds are attributed to the virtual account and destination wallet, Swipelux creates a pay-in transfer for the deposit and emits the normal transfer lifecycle webhooks. Completed attributed deposits also emit payin.completed. Incoming funds with missing or ambiguous attribution may require operational review and do not emit merchant lifecycle webhooks until they are resolved.

Endpoint Sequence

POST /v1/customers/{customerId}/rails
POST /v1/customers/{customerId}/wallets
POST /v1/customers/{customerId}/accounts
GET /v1/customers/{customerId}/accounts
GET /v1/transfers/{id}

API Reference