Create Virtual Wallet

Use the client virtual wallets endpoints to request onboarding and then list the resulting virtual account records.

Create Virtual Wallet

POST /api/v1/client/virtual-wallets

Request Body

FieldTypeRequiredDescriptionExample
user_idstring (UUID)YesCustomer user ID"123e4567-e89b-12d3-a456-426614174000"
currencystringYesWallet currency"CAD"

Example Request

json
{  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "currency": "CAD"}

Success Response

json
{  "message": "Customer onboarding completed successfully",  "currency": "CAD",  "user_id": "123e4567-e89b-12d3-a456-426614174000"}

Common Errors

Status CodeDescription
400Missing fields, invalid UUID, or invalid currency
401Invalid API key or signature
403User has not completed KYC
404No KYC record found for the supplied user
500Internal processing error

Processing Behavior

Virtual wallet creation is asynchronous.

  1. Submit the create request.
  2. Wait for the .
  3. Poll the list endpoint if you need to retrieve the created account details directly.

Setup typically completes within about 24 hours.

List Virtual Wallets

GET /api/v1/client/virtual-wallets

Returns one record per virtual bank account associated with your business.

Query Parameters

ParameterTypeRequiredDescription
user_idstring (UUID)NoFilter by customer
currencystringNoFilter by currency
created_between_fromstring (RFC3339)NoRange start
created_between_tostring (RFC3339)NoRange end
tzstring (IANA)ConditionalRequired when date range filters are used
limitintNoPage size, default 50, max 500
pageintNo1-based page number

Success Response Shape

json
{  "data": [    {      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",      "user_id": "123e4567-e89b-12d3-a456-426614174000",      "primary_wallet_id": "550e8400-e29b-41d4-a716-446655440000",      "business_id": "biz-uuid-here",      "is_business_primary_wallet": true,      "currency": "CAD",      "account_number": "1234567890",      "account_name": "John Doe",      "bank_name": "Example Bank",      "bank_code": "001",      "sort_code": "",      "bic_or_swift_code": "",      "routing_number": "",      "iban": "",      "email": "customer@example.com",      "country_code": "CA",      "bank_address": "",      "bank_beneficiary_address": "",      "is_primary": true,      "is_active": true,      "created_at": "2025-01-30T10:00:00Z",      "updated_at": "2025-01-30T10:00:00Z"    }  ],  "pagination": {    "total": 1,    "page": 1,    "size": 50,    "total_pages": 1  }}

Related Pages