VirtualPay · Operations

Notifications & error codes

Receive real-time transaction notifications on your callback endpoint and use the published error catalogue to handle common authentication, request, transaction and account failures.

POST

VirtualPay callback

Your callback endpoint

This API will be triggered to notify merchants in real time whenever a transaction occurs on a virtual account. The endpoint is provided by the client.

Request parameters

customer_idstringThe unique identifier of the customer initiating the transaction.

virtual_account_nostringThe virtual account number involved in the transaction.

virtual_account_namestringThe name associated with the virtual account.

transaction_amountstringThe total amount involved in the transaction.

transaction_feestringFee charged for the transaction.

transaction_referencestringA unique identifier for the transaction.

bo_referencenostringA reference number provided by the back office.

source_accountstringThe originating account number for the transaction.

source_account_namestringThe name associated with the source account.

source_bankstringThe bank name of the source account.

source_bank_codestringThe bank code of the source account’s bank.

narrationstringA description or purpose of the transaction.

session_idstringSwitch session ID for the transaction.

transaction_datestringThe date of the transaction.

tran_response_codestringCode indicating the transaction response (e.g., 00 for success).

tran_response_messagestringA message providing information about the transaction’s status.

channel_codestringAn identifier for the transaction channel, such as VIRTUALPAY.

payment_statusstringComplete or Amount Mismatch for retail transactions.

// request sent to your endpoint
{
  "customer_id": "08123456789",
  "virtual_account_no": "1578000000",
  "virtual_account_name": "JOHN DOE",
  "transaction_amount": "1500",
  "transaction_fee": "0.84",
  "transaction_reference": "VPAYTO1287139954",
  "bo_referenceno": "099MJKL212640002",
  "source_account": "0760261888",
  "source_account_name": "RICE DUMO",
  "source_bank": "Access Bank",
  "source_bank_code": "044",
  "narration": "TESTING",
  "transaction_date": "06-07-2022",
  "session_id": "100004241002184852120107569806",
  "tran_response_code": "00",
  "tran_response_message": "Successful Request",
  "channel_code": "VIRTUALPAY",
  "transaction_type": "static",
  "payment_status": "Complete"
}

Error codes

The published catalogue groups common VirtualPay failures into authentication, request, transaction and account errors.

Published errors

1001Invalid API KeyUse a valid API key.

1002Missing API KeyInclude your API key in the request headers.

2001Invalid Request ParametersVerify request parameters.

2002Unsupported Request MethodCheck API documentation for the correct method.

3001Insufficient FundsEnsure the account has sufficient funds.

3002Transaction Limit ExceededAdjust the transaction amount.

4001Account Not FoundVerify account details.

4002Account BlockedContact support.