🏦 Virtual Account (DVA)

The Virtual Account resource enables businesses to generate unique, trackable bank account numbers for collecting payments from customers. Each Dynamic Virtual Account (DVA) is linked to a wallet, automatically credits the wallet when funded, and supports advanced validation rules.

🔗 How It Works

A business creates a DVA with specific rules: fixed amount, minimum/maximum amount, or any amount.
The DVA is assigned a unique 10-digit account number that the business shares with their customer.
The customer transfers funds to that account number via bank transfer, USSD, or any payment channel.
Pandascrow receives the webhook, validates the payment against the DVA's rules, and instantly credits the business's wallet.
The business is notified via webhook to their registered application, and the customer receives a payment confirmation.

💼 Use Cases

E-commerce checkout - Generate a unique DVA for each order with the exact order amount.
Invoice collection - Create DVAs for invoices with minimum payment requirements.
Subscription billing - Generate new DVAs for each billing cycle or use static VAs for recurring customers.
Escrow funding - Allow buyers to fund escrow via bank transfer without needing a wallet.
Merchant settlements - Collect payments from multiple customers into a single wallet with payment tracking.

✨ Features

Dynamic or Static - Create temporary DVAs that expire or permanent static VAs.
Amount validation - Enforce exact amounts, minimums, maximums, or allow any amount.
Expiry control - Set expiry in hours (1-24) for time-sensitive payments.
Instant wallet credit - Funds are automatically credited to the business wallet in real time.
Beneficiary routing - Optionally route funds directly to a beneficiary account with one line of code.
Webhook notifications - Receive real-time payment alerts to your application.
Duplicate detection - Prevents double crediting with idempotency keys.
Hash verification - Cryptographic webhook validation prevents fake payment attacks.

📦 Virtual Account Types

Type	Description	Use Case
DYNAMIC	Temporary account that expires after set hours. Regenerates reference on each use.	One-time payments, order-based collection
STATIC	Permanent account that never expires. Same account number for all payments.	Recurring customers, subscription collections

💰 Amount Types

Type	Description	Example
`EXACT`	Customer must pay the exact amount	Invoice for ₦10,000 → customer pays exactly ₦10,000
`ANY`	Customer can pay any amount	Donations, flexible payments
`HIGHEROREXACT`	Customer must pay at least the specified amount	Minimum deposit of ₦5,000 → customer pays ₦7,500
`LOWEROREXACT`	Customer must pay at most the specified amount	Maximum payment of ₦50,000 → customer pays ₦30,000

🧾 Data You Can Attach

Field	Description
`uuid`	Unique identifier of the DVA record
`wallet_id`	ID of the wallet credited when funded
`wallet_uuid`	UUID of the wallet owner
`account_number`	10-digit 9PSB virtual account number
`account_name`	Name displayed on the virtual account
`bank_code`	9PSB bank code (120001)
`bank_name`	Bank name (9PSB)
`account_type`	`DYNAMIC` or `STATIC`
`reference`	Your unique transaction reference
`amount`	Expected amount (for EXACT/HIGHEROREXACT/LOWEROREXACT)
`currency`	Currency (NGN only)
`description`	Optional description for the DVA
`amount_type`	`EXACT`, `ANY`, `HIGHEROREXACT`, or `LOWEROREXACT`
`expiry_hours`	Hours until DVA expires (DYNAMIC only, 1-24)
`expiry_date`	Timestamp when DVA expires
`status`	`ACTIVE`, `FUNDED`, `EXPIRED`, or `DEACTIVATED`
`total_funded_amount`	Total amount received across all payments
`funding_count`	Number of successful payments received
`last_funded_amount`	Amount of the most recent payment
`last_funded_date`	Timestamp of the most recent payment
`last_funded_reference`	Transaction reference of the most recent payment
`beneficiary_account_number`	Optional account for direct settlement
`beneficiary_bank_code`	Beneficiary bank code
`beneficiary_fee_amount`	Fee amount for beneficiary routing
`created_at`	When the DVA was created
`updated_at`	Last time DVA details were updated

🔐 Security & Controls

Hash validation - Every webhook includes a cryptographic signature using your secret password.
Idempotency - Duplicate webhooks are automatically detected and rejected.
IP whitelisting - Optional restriction to Pandascrow's official IP ranges.
Amount validation - Prevents over/under payments based on DVA rules.
Expiry enforcement - Expired DVAs automatically reject payments.
Status tracking - Funded DVAs can be deactivated to prevent reuse.

📡 Webhook Events

Event	Description
`wallet.deposit.success`	A payment was received to a DVA and the wallet was credited

Webhook Payload Example

{
  "event": "wallet.deposit.success",
  "uuid": "merchant-uuid-here",
  "amount": 25000,
  "currency": "NGN",
  "transaction_ref": "DVA_20260606222716_959",
  "nipsessionid": "999169231016134100460496227401",
  "sender_name": "John Doe",
  "account_number": "5030000013",
  "memo": "DVA Payment from John Doe to 5030000013",
  "dva": {
    "record_uuid": "dva-record-uuid",
    "reference": "DVA_20260606222716_959",
    "account_name": "Acme Store",
    "amount_type": "EXACT",
    "expected_amount": 25000,
    "total_funded_amount": 25000,
    "funding_count": 1,
    "expiry_date": "2026-06-07 11:30:00"
  }
}