Skip to navigation
Virtual Accounts

Generate Virtual Account

View as Markdown

Generates a single-use virtual account number for collecting exactly amount. Minimum ₦1,000, maximum ₦10,000,000.

settlementId is optional: if provided, the funds are credited to that settlement (wallet) account instead of your default one. You are notified by webhook when it’s funded (see Webhooks You’ll Receive).

Body (JSON)

FieldTypeRequiredRules
amountnumberyes1,000 - 10,000,000 (NGN). Send as a JSON number.
settlementIdintegernoOne of your settlement account IDs. Send as a JSON number. A numeric string passes the check but makes the database lookup fail.

Behaviour notes

  • Returns a single-use account to collect exactly amount before expiryDate.
  • Keep virtual_trx_id: it’s the :transactionId for Fetch Virtual Account Transaction.
  • reference is the provider’s external reference, which is also sent in the funding webhook.
  • bankName in this response is always SAFEHAVEN MICROFINANCE.
  • The error text for amounts over the maximum says 1000000, but the real limit is ₦10,000,000.
  • All errors are HTTP 400 with { status: "error", message }.

Authentication

AuthorizationBearer

Access token from Generate Access Token (valid 15 minutes).

Request

This endpoint expects an object.
amountintegerOptional
settlementIdintegerOptional

Response

OK
statusstringOptional
dataobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error