Docs Dedicated Virtual Accounts

Dedicated Virtual Accounts

Dedicated Virtual Accounts allow your users to have permanent bank accounts tied to their profile. Users can deposit money into these accounts at any time, and your system will be notified instantly via webhooks.

Permanent Mapping

Once generated, the account remains active indefinitely. Perfect for wallet funding or user-specific collection points.

Auto-Confirmation

Every deposit triggers a transaction.success webhook automatically. No manual intervention required.

Create Dedicated Account

Generate a unique virtual account for a user. If the customer does not exist, HwebPay will create one automatically.

POST /v1/dedicated-virtual-accounts

Parameter	Required	Description
customer	YES	Object containing customer details.
↳ first_name	YES	Customer's first name.
↳ last_name	YES	Customer's last name.
↳ email	YES	Customer's unique email address.
↳ bvn	-	11-digit Bank Verification Number. Required for Tier 3 accounts.

Request Example

curl -X POST https://api.hwebpay.com/api/v1/dedicated-virtual-accounts \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer": {
    "first_name": "Seyi",
    "last_name": "Vibe",
    "email": "seyi@example.com",
    "phone": "08012345678",
    "bvn": "22233344455"
  }
}'

Webhooks & Notifications

When a customer transfers money to their dedicated virtual account, HwebPay will send notifications to your configured endpoints.

Dedicated Webhook URL

You can configure a separate **Dedicated VA Webhook URL** in your Dashboard Settings. This allows you to isolate permanent account deposits from standard checkout payments.

Default: Uses standard Webhook URL if dedicated URL is not set.

Supported Events

transaction.success Standard transaction payload including fees and metadata.
transfer.received Simplified payload optimized for credit-only notifications.

Webhook Payload (transfer.received)

{
  "event": "transfer.received",
  "data": {
    "amount": 500000,
    "account_number": "0123456789",
    "source": "JOHN DOE",
    "reference": "NIP-202310...",
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000"
  },
  "created_at": "2023-10-27T10:00:00Z"
}

Webhook Implementation (Secure PHP Sample)

Your webhook endpoint should verify the signature sent by HwebPay to ensure the request is authentic and hasn't been tampered with.

webhook-handler.php

// 1. Retrieve the signature and timestamp headers
$signature = $_SERVER['HTTP_X_HWEBPAY_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_HWEBPAY_TIMESTAMP'] ?? '';

// 2. Get the raw request body
$payload = file_get_contents('php://input');

// 3. Verify Timestamp (Prevent Replay Attacks)
if (abs(time() - (int)$timestamp) > 300) {
  http_response_code(400);
  exit('Request timeout');
}

// 4. Calculate Signature using your Webhook Secret
$secret = 'YOUR_WEBHOOK_SECRET';
$expectedSignature = hash_hmac('sha512', $timestamp . '.' . $payload, $secret);

// 5. Compare signatures securely
if (hash_equals($expectedSignature, $signature)) {
  // Success! Process the event
  $event = json_decode($payload, true);
  if ($event['event'] === 'transfer.received') {
    // Credit user wallet based on $event['data']['account_number']
  }
  http_response_code(200);
} else {
  // Invalid signature
  http_response_code(401);
}

Always use HMAC

Never trust a request without verifying the sha512 hash using your secret.

Check Timestamps

Ensure the request timestamp is within 5 minutes to prevent replay attacks.

Respond Quickly

Return a 200 OK immediately before doing heavy processing to avoid timeouts.

Fetch All Accounts

GET /v1/dedicated-virtual-accounts

Returns a paginated list of all dedicated virtual accounts created by your business.

Split Payments

Subscriptions

Developer Community