Virtual Accounts

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

Generate Virtual Account

Create a new virtual account number for your customer.

Endpoint

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

Body Parameters

Send exactly one of bvn or nin. If both are provided, bvn takes precedence.

Request Examples

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

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

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

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

Important Notes