Opay Charge

OPay charges are processed asynchronously. After you initiate a charge, HoneyCoin briefly checks for the first actionable transaction state before returning a response.

If a redirect URL is already available, the response includes stepRequired: "redirect" and redirectUrl, so you can immediately redirect your customer to complete payment authorization.

If no actionable state is available yet, the response returns status: "PENDING" and chargeStatus: "pending". Continue tracking the transaction using webhooks or the Get Transaction endpoint.

Always verify the final transaction status before providing value to your customer. A transaction is only successful when chargeStatus is successful.

1 - Initiate Opay Charge

Field	Type	Required	Description
amount	Number	✅	Amount to charge (e.g. 100)
externalReference	String	✅	Your unique reference
currency	String	❌	3-letter currency code. Defaults to NGN
email	String	❌	Customer email
successRedirectUrl	String	❌	Optional redirect URL for a success case
failureRedirectUrl	String	❌	Optional redirect URL for a failed case

Note: The opay charge is processed asynchronously. Use the transactionId to track status via the get transaction endpoint or listen for webhooks.

To charge a customer, collect the required opay details and send them to the opay charge endpoint.

Example Request:

{
    "amount": 100,
    "currency": "NGN",
    "email": "[email protected]",
    "externalReference": "nvcmnvnmclmlv",
    "successRedirectUrl": "https://www.google.com/",
    "failureRedirectUrl": "https://x.com/"
}

{
    "amount": 100,
    "externalReference": "nvcmnvnmclmlv"
}

Below is an example of the response:

{
    "success": true,
    "message": "Transaction initiated successfully.",
    "data": {
        "transactionId": "6VOWReShlbh4MzXu8kbQ"
    }
}

2 - Handle the Initial Response

The initiatial response may return one of these states.

{
  "success": true,
  "message": "Transaction initiated successfully.",
  "data": {
    "transactionId": "txn_123",
    "status": "PENDING",
    "chargeStatus": "pending"
  }
}

{
  "success": true,
  "message": "Transaction initiated successfully.",
  "data": {
    "transactionId": "txn_123",
    "status": "PENDING",
    "chargeStatus": "pending",
    "stepRequired": "redirect",
    "redirectUrl": "https://checkout.example.com/pay"
  }
}

Pending: No redirect or final status is available yet. Store the transactionId and wait for a webhook or query the Get Transaction endpoint.

Redirect Required: Redirect the customer to redirectUrl to complete payment authorization.

3 - Redirect the Customer

If the response includes:

{
  "stepRequired": "redirect",
  "redirectUrl": "https://checkout.example.com/pay"
}

send your customer to the redirectUrl.

After the customer completes the payment flow, do not rely only on the redirect back to your application. Always confirm the final transaction status through a webhook or the Get Transaction endpoint.

4 - Verify Transaction Status

Always verify the payment status before providing value to your customer. Use the get transaction endpoint with either:

The transactionId from the charge response or
Your externalReference

Here's an example of the transaction object once a redirect url is retrieved:

{
    "success": true,
    "data": {
        "transactionId": "ARKHAM-ASYLUM-777",
        "amount": 500,
        "currency": "NGN",
        "createdAt": 1772739766529,
        "chargeStatus": "pending",
        "receiverCurrency": "NGN",
        "receiverAmount": 500,
        "senderCurrency": "NGN",
        "senderAmount": 500,
        "status": "PENDING",
        "type": "deposit",
        "method": "opay",
        "fullTimestamp": "2026-03-05T19:42:46+00:00",
        "externalReference": "PUDDIN-01",
        "stepRequired": "redirect",
        "redirectUrl": "https://redirect.com"
    }
}

{
  "success": true,
  "data": {
    "transactionId": 'lBK9bMny2gs4hLsG3XGq',
    "amount": 25,
    "type": 'deposit',
    "currency": 'NGN',
    "senderCurrency": 'NGN',
    "senderAmount": 25,
    "receiverCurrency": 'NGN',
    "receiverAmount": 25,
    "chargeStatus": 'successful',
    "status": 'SUCCESSFUL',
    "method": 'opay',
    "fullTimestamp": '2025-06-17T01:16:44+03:00',
    "externalReference": "test",
    "phoneNumber": '253722446688'
  }
}

5 - Handle Webhooks

Configure webhooks to receive real-time transaction updates instead of polling the status endpoint.

Setup

Configure your webhook URL in your dashboard.
Implement webhook endpoint security and validation.
Handle the webhook notifications in your application.

{
    "event": "transaction_updated",
    "data": {
        "transactionId": "RFJZcgeeTGilZgPp9zyn",
        "status": "pending",
        "type": "deposit",
        "stepRequired": "redirect",
        "externalReference": "12fd3456789x",
        "redirectUrl": "https://redirect.com"
    },
    "timestamp": "2026-03-05T19:42:56.538Z"
}

When a stepRequired field is present:

redirect — Redirect the customer to the provided redirectUrl to complete the payment.