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
412Required KYC data is missing or the provider rejected the virtual wallet creation precondition
500Internal processing error

When KYC data is incomplete for provider virtual account creation, the response includes the missing fields:

json
{  "error": "missing required KYC fields for virtual account creation",  "code": "missing_kyc_fields",  "missing_fields": ["id_expiry_date"],  "action": "update the customer KYC record and retry virtual wallet creation"}

Processing Behavior

Virtual wallet creation is asynchronous.

  1. Submit the create request.
  2. Wait for the virtual wallet webhook.
  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