Opay Charge

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 - Get 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'
  }
}

3 - 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.