Virtual Accounts - Gafiapay API Documentation

Learn how to create and manage virtual accounts using the Gafiapay API.

Generate Virtual Account

Create a new virtual account number for your customer.

One customer identifier (optional)

Include only one of bvn, nin, or businessNumber—whichever matches that customer. You do not need to send all three. If you omit all of them, Gafiapay uses your merchant compliance identity (unchanged behaviour). If you send more than one by mistake, the API picks a single value using this order: CAC / business number → BVN → NIN.

Endpoint

POST /account/generate

Authentication

This endpoint requires API key authentication. Include your API key in the request headers:

{
  "x-api-key": "your_api_key",
  "x-signature": "generated_signature",
  "x-timestamp": "current_timestamp"
}

Request Parameters

Headers

Name	Type	Required	Description
`x-api-key`	string	Yes	Your API key
`x-signature`	string	Yes	Request signature
`x-timestamp`	string	Yes	Current timestamp
`Content-Type`	string	Yes	application/json

Body Parameters

Name	Type	Required	Description
`name`	string	Yes	Customer's full name
`email`	string	Yes	Customer's email address
`bvn`	string	No	Optional: use this or `nin` or `businessNumber`—not all three. Customer BVN (11 digits); sent as `identityType: personal`. If omitted (and the other two are omitted), merchant compliance identity is used.
`nin`	string	No	Optional: one-of-three (see above). Customer NIN (11 digits); sent as `identityType: personal_nin`. Aliases: `NIN`, `ninNumber`.
`businessNumber`	string	No	Optional: one-of-three (see above). CAC / company registration (must start with `RC` or `BN`, or digits only—we prefix `RC`). Sent as `identityType: company`. Aliases: `cac`, `companyRegistrationNumber`, `businessRegistrationNumber`.

Prefer sending one field only. If multiple are present, the API uses businessNumber (CAC) first, then bvn, then nin.

Request Example

{
  "name": "John Doe",
  "email": "john@example.com"
}

Request example (with customer BVN)

{
  "name": "John Doe",
  "email": "john@example.com",
  "bvn": "22345678901"
}

Response Example

{
  "status": "success",
  "data": {
          "bankName": "Virtual Bank",
    "accountNumber": "1234567890",
    "accountName": "John Doe",
    "userName": "John Doe"
  }
}

Error Responses

400 Bad Request - Missing Required Fields

{
  "status": "fail",
  "message": "name is required"
}

400 Bad Request - Virtual Account API Error

{
  "status": "fail",
  "message": "Virtual account error message from external API"
}

500 Internal Server Error

{
  "status": "fail",
  "error": "Internal server error details"
}

Important Notes

🔄 Account Reuse

If an account already exists for the provided email and business, the existing account will be updated with the new account number from our virtual account system.

🏦 Virtual Account System

Virtual accounts are generated through our secure API. The account numbers are 10-digit virtual account numbers provided by our system.

📋 Identity for generation

Permanent (POST /account/generate) and temporary (POST /account/generate/temporary) use the same rules: send one optional customer identifier (bvn, nin, or businessNumber), or omit all three to use merchant compliance. Values must match Gafiapay's virtual account identity rules.

Generate temporary virtual account

Create a time-limited virtual account (label). Optional KYC is the same as permanent generation: include only one of bvn, nin, or businessNumber when you want the customer's identity on the label. If you omit all three, your merchant's compliance identity is used and the business must have completed verification (compliance.verificationStatus === 'completed').

Endpoint

POST /account/generate/temporary

Authentication

Same as permanent generation: API key, signature, and timestamp headers.

Body parameters

Name	Type	Required	Description
`name`	string	Yes	Customer display / virtual account name
`email`	string	Yes	Customer email
`duration`	number	No	Expiry in minutes from creation. Default `40`. Response includes `expiresInMinutes` and persisted `expiresAt`.
`bvn`	string	No	Optional: one of three (see callout above). Customer BVN (11 digits). Alias: `BVN`.
`nin`	string	No	Optional: one of three. Customer NIN. Aliases: `NIN`, `ninNumber`.
`businessNumber`	string	No	Optional: one of three. CAC / company registration. Aliases: `cac`, `companyRegistrationNumber`, `businessRegistrationNumber`.

Prefer one field only. If several are sent, the API chooses businessNumber first, then bvn, then nin.

Request example

{
  "name": "Jane Customer",
  "email": "jane@example.com",
  "duration": 60,
  "nin": "12345678901"
}

Response shape

On success, status is success and data includes the created account document (including isTemporary: true, expiresAt) plus expiresInMinutes.

Authentication

List Accounts