SZNDSZND
Get Started
IntroductionAuthenticationCollectionsPayoutsWalletsQuotesWebhooksPlayground

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. Client API supports EUR, GBP, and NGN"GBP"
bvnstringRequired for NGNCustomer BVN (exactly 11 digits). Required by Bank78 for static NUBAN creation"01234567890"
account_namestringNoDisplay name on the NGN virtual account (3–100 chars). If omitted for NGN, defaults to {BusinessName} {CustomerFirst} {CustomerLast}"Breeze Customer A"

Example Request (GBP)

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

Example Request (NGN)

json
{  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "currency": "NGN",  "bvn": "01234567890",  "account_name": "Breeze Customer A"}

Success Response

Creation is asynchronous when a new wallet is provisioned:

json
{  "message": "Customer onboarding initiated successfully",  "currency": "GBP",  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "status": "PENDING"}

If the customer already has a virtual wallet for that currency, the existing account is returned instead of creating another one:

json
{  "message": "Virtual wallet already exists for this customer and currency",  "currency": "GBP",  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "status": "ACTIVE",  "already_exists": true,  "virtual_wallet": {    "id": "550e8400-e29b-41d4-a716-446655440000",    "currency": "GBP",    "account_number": "12345678",    "sort_code": "040075",    "is_active": true  }}

Common Errors

Status CodeDescription
400Missing fields, invalid UUID, unsupported currency, or missing bvn for NGN
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 virtual wallet creation precondition was not met
500Internal processing error

When KYC data is incomplete for 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 (CAD, EUR, GBP, NGN)
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

CAD Interac

To retrieve Interac collection credentials for your customers, filter with currency=CAD:

http
GET /api/v1/client/virtual-wallets?currency=CAD&page=1&limit=50

Each CAD row includes:

FieldMeaning
user_idCustomer ID
emailInterac collection email
questionSecurity question
answerSecurity answer

Treat question and answer as confidential. Optional: pass user_id to fetch one customer.

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": "INTERAC",      "bank_code": "",      "sort_code": "",      "bic_or_swift_code": "",      "routing_number": "",      "iban": "",      "email": "johndoe12345@example.com",      "question": "What is the secret code?",      "answer": "48291",      "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