DevelopersVirtual AccountCreate a Virtual Account
Create a Virtual Account
Use this endpoint to generate a new virtual account number. The account is immediately active upon successful creation.
Endpoint
POST/virtual/new-account
Headers
| Header | Value | Description |
|---|---|---|
| Content-Type | application/jsonRequired for all requests. | |
| secretKey | <your-secret-key>The API key issued by KongaPay for your environment. |
💡
API keys are not self-served from the dashboard. After registering on the Staging or Production platform, contact the KongaPay support team to request your API keys for that environment.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | Your unique identifier for this payment. Stored as external_reference. |
| account_name | string | Yes | The display name for the virtual account. |
| merchant_id | string | Yes | Your merchant identifier. |
| amount | number | Cond. | Expected payment amount in Naira. Required for nonstatic and static. Omit for static-flex. |
| expiers_in | number | Cond. | Expiry duration in minutes. Required for nonstatic. Ignored for static and static-flex. |
| type | string | Yes | Virtual account type: nonstatic, static, or static-flex. |
| callback_url | string | Yes | The URL KongaPay will POST payment notifications to. |
| merchant | string | Yes | Merchant category. Use "others" if not pre-classified. |
⚠️
Note the intentional spelling of
expiers_in — this is the correct field name in the API. Do not correct it to expires_in.Sample Request
Request
POST /virtual/new-account
Content-Type: application/json
secretKey: sk_staging_xxxxxxxxxxxxxxxxxxxx
{
"reference": "INV-2026-0001",
"account_name": "Acme Stores Order 12093",
"merchant_id": "M-001",
"amount": 5000,
"expiers_in": 30,
"type": "nonstatic",
"callback_url": "https://merchant.example.com/webhook",
"merchant": "others"
}Success Response
HTTP 200 OK
Response
{
"status": "success",
"data": {
"account_number": "5001234567",
"account_name": "Acme Stores Order 12093",
"reference": "KP-VIR-XXXX",
"Bank": "KongaPay",
"external_reference": "INV-2026-0001",
"status": "active"
}
}Error Responses
| HTTP Status | Code | Error | Resolution |
|---|---|---|---|
| 400 | — | Bad Request | Missing or invalid fields, or secretKey not provided. |
| 404 | — | Not Found | The settlement account linked to secretKey does not exist. |
| 409 | — | Conflict | A virtual account with this reference already exists. |