Callback

Receiving a callback

Creating an endpoint to receive callbacks on your application is as easy as creating a new page that accepts unauthenticated POST requests. The callback object is sent as JSON in the request body.

Confirming callback

Since anyone can get hold of your endpoint and attempt to send you phony event objects for malicious purposes (e.g. to see if they can mark their subscription to your product as renewed just in case you aren't running any verifications on the transaction reference), it is important to verify that callbacks originate from OPay.

You can do any or both of the list below to verify callbacks from OPay:

Watch the IPs and accept callbacks only from our IPs
Validate the Signature as decribed in the section that follows

Responding to a callback

You should respond to a callback with a 200 OK. We consider this an acknowledgement by your application. If your application responds with any status outside of the 2xx range, we will consider it unacknowledged and thus, continue to send it for 72 hours. You don't need to send a request body or some other parameter as it would be discarded - we only pay attention to the status code.

Structure of an callback object

A callback object is sent in JSON and similar to what you would get in response to a typical API request. Below is the body of a callback.

Sample Response

{
  "payload": {
    "country": "NG",
    "instrumentId": "useless",
    "fee": "0.10",
    "channel": "Web",
    "displayedFailure": "",
    "reference": "3cae64cb5f68a7c4008b765b97401a",
    "updated_at": "2020-09-21T13:18:45Z",
    "currency": "NGN",
    "refunded": false,
    "instrument-id": "useless",
    "timestamp": "2020-09-21T13:18:45Z",
    "amount": "10.00",
    "sessionId": "100004210318204012100247394470",
    "instrumentType": "coins",
    "instrument_id": "useless",
    "transactionId": "200921144008250432",
    "token": "200921144008250432",
    "bussinessType": "Consumption_H5",
    "payChannel": "BalancePayment",
    "status": "successful"
  },
  "sha512": "4d001b261faa72096b63fa024299fd860c17b98563d4bb4f72371b932b91c348959f3af98853a37347b09a84ddcf53203d49f77d715f1679d8598f7a54107ef4",
  "type": "transaction-status"
}

RESPONSE PROPERTY	DESCRIPTION
payload.country	Transaction belongs country
payload.fee	Transaction fee Amount in NGN
payload.displayedFailure	Transaction reason for failure
payload.reference	Partner transaction number
payload.updated_at	Transaction update time
payload.currency	Transaction currency
payload.refunded	Is the transaction a refund type (true or false)
payload.timestamp	Transaction time
payload.amount	Transaction Amount in NGN
payload.transactionId	OPay transaction number
payload.payChannel	Pay method (BankCard BalancePayment OWealth FlexiFixed BonusPayment)
payload.status	Transaction status (successful or failed)
sha512	which is essentially a HMAC-SHA3-512 signature of the callback payload. Signed using your Secret Key
type	transaction-status

HMAC-SHA3-512 signature of the callback payload

Valid callbacks are raised with sha512 value, which is essentially a HMAC-SHA3-512 signature of the callback payload. Yes, signed using your Secret Key.

Example signature payload params

There are two values for Refunded, when payload.refunded is true, it is t, otherwise it is f.

{Amount: "10.00",Currency:"NGN",Reference:"3cae64cb5f68a7c4008b765b97401a",Refunded: f,Status: "successful",Timestamp: "2020-09-21T13:18:45Z",Token: "200921144008250432",TransactionID:"200921144008250432"}

Receiving a callback
Confirming callback
Responding to a callback
Structure of an callback object
HMAC-SHA3-512 signature of the callback payload