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

Field	Type	Required	Description
`event_type`	string	Yes	Always `"virtual_bank_account"` for this webhook type
`currency`	string	Yes	Currency code of the virtual wallet (e.g., `"USD"`, `"GBP"`, `"EUR"`, `"CAD"`)
`wallet_id`	string	Yes	Unique identifier for the wallet in Transfaar's system (UUID format)
`customer_id`	string	Yes	Unique identifier for the customer/user who owns the wallet (UUID format)
`timestamp`	string	Yes	RFC3339 timestamp indicating when the wallet was created (UTC)
`status`	string	Yes	Current status of the wallet (e.g., `"ACTIVE"`, `"IN_PROGRESS"`)
`account_info`	object	No	Virtual bank account details (may be omitted if not yet available)

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:

Field	Type	Description
`account_number`	string	The virtual bank account number
`account_name`	string	The name associated with the account
`bank_name`	string	Name of the bank providing the virtual account
`bank_code`	string	Bank code identifier (if applicable)
`sort_code`	string	Sort code for UK/Ireland accounts (format: `"12-34-56"`)
`swift_code`	string	BIC/SWIFT code for international transfers
`routing_number`	string	Routing number for USD ACH transfers
`iban`	string	IBAN for EUR/GBP accounts
`bank_address`	string	Physical address of the bank
`country_code`	string	ISO 3166-1 alpha-2 country code (e.g., `"GB"`, `"US"`)
`account_type`	string	Type of account: `"Checking"` or `"Savings"`

Status Values

Status	Description
`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

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

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.
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
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)
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.

Transaction Webhook KYC Completion