Skip to main content

​
Virtual Accounts

​
Create Virtual Account (API Key)

POST /business/virtual-account/create

​
Request Body

{
  "businessId": "664b...",
  "amount": 5000,
  "reference": "NexaWallet-20260313",
  "merchantCustomerId": "cust_12345",
  "merchantReference": "order_90881",
  "sessionId": "session_7781",
  "orderId": "order_90881",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "customerPhone": "08055555555",
  "metadata": {
    "purpose": "wallet_topup",
    "source": "checkout"
  },
  "validityTime": "2400",
  "amountValidation": "A3"
}
Notes:
  • businessId, amount, reference, merchantCustomerId, and merchantReference are required.
  • merchantCustomerId should match the merchant’s internal user/customer ID.
  • merchantReference should match the merchant’s own order/session/invoice reference.
  • Any extra mapping fields are preserved in metadata and echoed back in the deposit webhook.

​
Response (Production)

{
  "success": true,
  "msg": "Virtual account created successfully",
  "accountNumber": "4600070017",
  "reference": "NexaWallet-20260313",
  "transactionId": "NexaWallet-20260313",
  "environment": "prod",
  "simulated": false,
  "virtualAccount": {
    "businessId": "664b...",
    "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "amount": 5000,
    "validityTime": "2400",
    "amountValidation": "A3",
    "sessionId": "session_7781",
    "orderId": "order_90881",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "08055555555",
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout"
    }
  }
}

​
Response (Test Key)

{
  "success": true,
  "msg": "Test virtual account created successfully",
  "accountNumber": "9123456789",
  "reference": "TEST-VA-1710000000000",
  "transactionId": "TEST-VA-1710000000000",
  "environment": "test",
  "simulated": true,
  "virtualAccount": {
    "businessId": "664b...",
    "merchantCustomerId": "cust_12345",
    "merchantReference": "order_90881",
    "amount": 5000,
    "validityTime": "2400",
    "amountValidation": "A3",
    "sessionId": "session_7781",
    "orderId": "order_90881",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "08055555555",
    "metadata": {
      "purpose": "wallet_topup",
      "source": "checkout"
    }
  }
}

​
Error Response

{
  "success": false,
  "msg": "businessId, amount and reference are required"
}

​
Virtual Account History

GET /business/virtual-account/history Includes expiresAt and status (ACTIVE / EXPIRED). Also returns merchantCustomerId and merchantReference so you can map each virtual account back to the correct internal customer or order. This endpoint is currently available in the merchant dashboard only and is not exposed for server-to-server integrations.