Virtual Wallets Overview

Virtual wallets give your customers dedicated receiving accounts for supported currencies. Incoming transfers can then be associated with the correct wallet and customer.

What Virtual Wallets Provide

  • dedicated virtual account details for inbound transfers
  • support for multiple currencies
  • asynchronous wallet/account setup
  • webhook notifications when the account is ready

Supported Currencies

  • CAD
  • USD
  • EUR
  • GBP

Read This Section In Order

How The Flow Works

  1. You request virtual wallet onboarding for a specific customer and currency.
  2. The setup runs asynchronously.
  3. When the account becomes available, you receive a webhook notification.
  4. You can list virtual wallets to retrieve the resulting account details.

Related Pages

javascript
const crypto = require('crypto');
async function listVirtualWallets(queryParams = '') {  const apiKey = 'your_api_key_here';  const secretKey = 'your_secret_key_here';  const timestamp = new Date().toISOString();  const url = `https://api.sznd.app/api/v1/client/virtual-wallets${queryParams ? '?' + queryParams : ''}`;  const dataToSign = '' + '|' + timestamp; // GET: empty body  const signature = crypto.createHmac('sha256', secretKey).update(dataToSign).digest('hex');  const response = await fetch(url, {    method: 'GET',    headers: { 'x-api-key': apiKey, 'x-timestamp': timestamp, 'x-signature': signature }  });  return await response.json();}
const resp = await listVirtualWallets('user_id=123e4567-e89b-12d3-a456-426614174000&currency=CAD');console.log('Virtual wallets:', resp.data);console.log('Total:', resp.pagination.total, 'Page:', resp.pagination.page, 'of', resp.pagination.total_pages);

Get Virtual Wallet by ID

Retrieve all virtual bank account (VBA) details for a single wallet by wallet ID. The customer that owns the wallet must belong to your business.

Endpoint

GET /api/v1/client/virtual-wallets/:id

PartDescription
idWallet ID (UUID). Path parameter.

Authentication

Same as List: HMAC (Business API Key). See .

Success Response (200 OK)

Returns an array of virtual wallet detail objects (same shape as each item in the List response). One entry per VBA linked to that wallet. If the wallet has no VBAs, the array is empty.

json
[  {    "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",    "question": "What is the answer",    "answer": "0234568ZZ",    "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"  }]

Error Responses

Status CodeDescription
400Invalid wallet ID (not a valid UUID)
401Unauthorized - Invalid API key or signature
403Customer does not belong to your business
404Virtual wallet not found (wallet ID unknown or user has no BVA config for that wallet)
500Internal server error

Example: cURL

bash
curl -X GET "https://api.sznd.app/api/v1/client/virtual-wallets/550e8400-e29b-41d4-a716-446655440000" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"

Example: JavaScript

javascript
async function getVirtualWalletById(walletId) {  const apiKey = 'your_api_key_here';  const secretKey = 'your_secret_key_here';  const timestamp = new Date().toISOString();  const dataToSign = '' + '|' + timestamp;  const signature = crypto.createHmac('sha256', secretKey).update(dataToSign).digest('hex');  const response = await fetch(    `https://api.sznd.app/api/v1/client/virtual-wallets/${walletId}`,    {      method: 'GET',      headers: { 'x-api-key': apiKey, 'x-timestamp': timestamp, 'x-signature': signature }    }  );  return await response.json();}
const vbaList = await getVirtualWalletById('550e8400-e29b-41d4-a716-446655440000');console.log('VBAs for wallet:', vbaList);

Webhook Notification

When the virtual wallet is ready, a webhook will be sent to your configured webhook URL. The webhook payload will include:

  • Event type: virtual_wallet.ready
  • User ID and currency
  • Virtual wallet ID
  • Bank account details
  • Timestamp

Configure your webhook URL in your business settings to receive these notifications automatically. See the for more details.

Integration Flow

The complete virtual wallet integration follows these steps:

┌─────────────────────────────────────────────────────────────────┐│                    Virtual Wallet Onboarding Flow               │├─────────────────────────────────────────────────────────────────┤│                                                                 ││  1. Register Customer                                           ││     POST /api/v1/client/customers                               ││     └─> Returns user_id                                         ││                                                                 ││  2. Complete KYC Verification                                   ││     POST /api/v1/client/customers/kyc                           ││     └─> Customer completes KYC verification                     ││                                                                 ││  3. Onboard to Virtual Wallet                                   ││     POST /api/v1/client/virtual-wallets                         ││     └─> Initiates virtual wallet creation process                ││                                                                 ││  4. Wait for Processing (24 hours)                              ││     └─> Virtual wallet setup is processed asynchronously        ││     └─> Webhook notification sent when ready                    ││                                                                 ││  5. List or get virtual wallet details                         ││     GET /api/v1/client/virtual-wallets (list, optional filters)  ││     GET /api/v1/client/virtual-wallets/{wallet_id} (by wallet)   ││     └─> Returns array of VBA details (one item per virtual account) ││                                                                 ││  6. Customer Receives Virtual Account                           ││     └─> Virtual account number available                        ││     └─> Customer can receive deposits via bank transfer          ││                                                                 ││  7. Funds Available in Wallet                                   ││     └─> Incoming transfers credited automatically               ││     └─> Review wallet balances from your client wallet flows    ││                                                                 │└─────────────────────────────────────────────────────────────────┘

Step 1: Register Customer

First, register the customer using the Customer Registration endpoint:

bash
curl -X POST https://api.sznd.app/api/v1/client/customers \  -H "Content-Type: application/json" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -d '{    "email": "customer@example.com",    "first_name": "John",    "last_name": "Doe",    "phone_number": "+1234567890",    "country_code": "CA",    "date_of_birth": "1990-05-15"  }'

Step 2: Complete KYC

The customer must complete KYC verification. See the for details.

Step 3: Onboard to Virtual Wallet

Once KYC is complete, onboard the customer to the virtual wallet:

bash
curl -X POST https://api.sznd.app/api/v1/client/virtual-wallets \  -H "Content-Type: application/json" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -d '{    "user_id": "123e4567-e89b-12d3-a456-426614174000",    "currency": "CAD"  }'

Step 4: Wait for Processing

The virtual wallet setup is processed asynchronously and typically completes within 24 hours. You have two options:

Option A: Wait for Webhook Notification (Recommended)

Configure your webhook URL to receive a notification when the virtual wallet is ready. The webhook will include all bank account details.

Option B: Poll the list or get-by-id endpoint

After 24 hours, list virtual wallets (optionally filter by user_id, currency) or get by wallet ID:

bash
# List all VBAs for your business (optional: ?user_id=...&currency=...)curl -X GET "https://api.sznd.app/api/v1/client/virtual-wallets" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"
# Or get VBAs for a specific wallet by IDcurl -X GET "https://api.sznd.app/api/v1/client/virtual-wallets/550e8400-e29b-41d4-a716-446655440000" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"

Step 5: Use Virtual Account Details

Once the virtual wallet is ready, use the bank account details from the list or get-by-id response (each item has account_number, bank_name, iban, etc.) to receive deposits. The customer can receive funds via bank transfer using the provided account information.

Important Notes

KYC Requirement

The customer must have completed KYC verification before virtual wallet onboarding can proceed. The system checks the KYC status and will return a 403 error if KYC is not completed.

Idempotency

If a customer is already onboarded for a specific currency, the endpoint may return success if the wallet already exists.

Processing Time

The virtual wallet onboarding request is processed asynchronously. After submitting the POST request:

  • Processing Time: Virtual wallet setup typically completes within 24 hours
  • Webhook Notification: A webhook will be delivered to your configured webhook URL when the virtual wallet is ready
  • Retrieving Details: After 24 hours, you can list virtual wallets with GET /api/v1/client/virtual-wallets (optional filters: user_id, currency, pagination) or get by wallet ID with GET /api/v1/client/virtual-wallets/{id} to retrieve bank account details, or wait for the webhook notification

Virtual Account Details

After successful onboarding, the customer's wallet will include virtual account details (account number, bank name, etc.) that can be used to receive deposits. These details are available through the wallet API endpoints.

Related Resources

  • - View virtual wallet balances and details
  • - Customer registration and management
  • - KYC verification process
  • - View transaction history