Virtual Wallet Creation Webhook

Business clients receive real-time notifications when a virtual wallet (virtual bank account) is created for one of their customers. This client webhook is triggered automatically when a virtual wallet is successfully created through our system.

When is this webhook sent?

The virtual_bank_account webhook is sent when:

• A virtual wallet is successfully created for a customer that belongs to your business
• The virtual wallet creation is completed and the account details are available
• Your business API key has a webhook URL configured

Payload Schema

{  "event_type": "virtual_bank_account",  "currency": "USD",  "wallet_id": "550e8400-e29b-41d4-a716-446655440000",  "customer_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",  "timestamp": "2024-01-15T10:30:00Z",  "status": "ACTIVE",  "account_info": {    "account_number": "1234567890",    "account_name": "John Doe",    "bank_name": "Example Bank",    "bank_code": "123456",    "sort_code": "12-34-56",    "swift_code": "ABCDGB2L",    "routing_number": "021000021",    "iban": "GB82WEST12345698765432",    "bank_address": "123 Main Street, London, UK",    "country_code": "GB",    "account_type": "Checking"  }}

Payload Fields

Account Info Fields

The account_info object contains detailed information about the virtual bank account. All fields within account_info are optional and will only be included if available:

Status Values

Example Payloads

Example 1: USD Virtual Wallet

{  "event_type": "virtual_bank_account",  "currency": "USD",  "wallet_id": "550e8400-e29b-41d4-a716-446655440000",  "customer_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",  "timestamp": "2024-01-15T10:30:00Z",  "status": "ACTIVE",  "account_info": {    "account_number": "9876543210",    "account_name": "Jane Smith",    "bank_name": "US Bank",    "routing_number": "021000021",    "country_code": "US",    "account_type": "Checking"  }}

Example 2: GBP Virtual Wallet

{  "event_type": "virtual_bank_account",  "currency": "GBP",  "wallet_id": "660e8400-e29b-41d4-a716-446655440001",  "customer_id": "7ba7b810-9dad-11d1-80b4-00c04fd430c9",  "timestamp": "2024-01-15T11:45:00Z",  "status": "ACTIVE",  "account_info": {    "account_number": "12345678",    "account_name": "John Doe",    "bank_name": "UK Bank",    "sort_code": "12-34-56",    "swift_code": "ABCDGB2L",    "iban": "GB82WEST12345698765432",    "bank_address": "123 Main Street, London, UK",    "country_code": "GB",    "account_type": "Checking"  }}

Example 3: Minimal Payload (Account Info Not Yet Available)

{  "event_type": "virtual_bank_account",  "currency": "EUR",  "wallet_id": "770e8400-e29b-41d4-a716-446655440002",  "customer_id": "8ba7b810-9dad-11d1-80b4-00c04fd430c0",  "timestamp": "2024-01-15T12:00:00Z",  "status": "IN_PROGRESS"}

Important Notes

1. Account Info Availability: The account_info object may be omitted if account details are not yet available at the time the webhook is sent. In such cases, the webhook will still be sent with the basic wallet information, and you can query the wallet details later using the API.

2. Status Values: Common status values include:

   • "ACTIVE": The wallet is fully active and ready to use
   • "IN_PROGRESS": The wallet creation is still being processed
   • "NOT_ACTIVE": The wallet is not currently active
   • "DELETED": The wallet has been deleted

3. Webhook Security: This webhook uses the same security mechanism as transaction webhooks:

   • Signed with HMAC-SHA256 using your API key's secret
   • Includes X-Transfaar-Signature header for verification
   • Same retry logic applies (up to 10 attempts with exponential backoff, only retries if response is not 200 OK)

4. Idempotency: You should implement idempotency handling in your webhook receiver. The same wallet creation event may be sent multiple times if retries occur, so use the wallet_id to deduplicate.