OPay Wallet Payment

The OPay Wallet Payment API allows you to debit any of your customers’ OPay wallet for transactions initiated via your website or mobile app. The transaction will then be authorized using the customers’ PIN and uniquely generated OTP, details which will be forwarded to us via API.

Mandatory preparations to accept OPay wallet payments on your platform

  1. Create a merchant account here
  2. Go to “Settings” and Retrieve your Merchant ID.
  3. Go to “Settings” and click on the “API Keys & Webhooks” tab.
  4. Note your Secret & Public Keys as you’ll need them for your headers going forward.
  5. You could also specify a webhook URL if you desire to receive webhook transaction notifications from OPay.

Immediately the necessary credentials have been retrieved, kindly complete the following steps.


Step 1: Initialize a Wallet Payment transaction

Step 1a : Your customer is to provide the mobile number linked to his/her OPay account (otherwise known as Wallet Number). This information will be passed to OPay via the Initialize API.

Step 1b : Specify the API url for the Initialize API and arrange the headers using the API credentials fetched from your dashboard (header format is as specified below).

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/initialize

Sample Request

post/certpay/initialize
curl -X POST --header 'Authorization: Bearer public_key'
--header 'MerchantId: 256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/initialize

Step 1c : Arrange your request payload (which includes the customers’ wallet number and amount to be debited) and call the Initialize API. Kindly note that the Amount value is in Kobo.

Sample Request Body

post/certpay/initialize
{
  "reference": "test_20191123132233",
  "userPhone": "+2341234567890",
  "amount": "10000",
  "currency": "NGN",
  "userRequestIp": "123.123.123.123",
  "productName": "iPhone X",
  "productDesc": "The best iPhone",
  "expireAt": "10"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
userPhoneUser's mobile phone number. e.g. +2349876543210
amountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
userRequestIpThe IP address requested by user, need pass-through by merchant, user Anti-phishing verification
productNameProduct name, utf-8 encoded
productDescProduct description, utf-8 encoded
expireAtTransaction would be closed within specific time. Value is in minute

Sample Response

post/certpay/initialize
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "reference": "test_20191123132233",
    "orderNo": "210329290539846954",
    "userPhone": "+2341234567890",
    "amount": "10000",
    "currency": "NGN",
    "status": "INITIAL"
  }
}
RESPONSE PROPERTYDESCRIPTION
orderNoOrder number from OPay payment
referenceOrder number of merchant (unique order number from merchant platform)
amountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
statusINITIAL

Things To Note

1.If an issue occurs and OPay couldn’t accept the transaction for processing, the appropriate error code and reason will be returned in the code and message fields. Please see a sample below.

{
  "code": "04999",
  "message": "T.TT.I.04999 Transaction is being processed",
  "data": null
}

2.If OPay receives the API call & accepts it for processing, the code and message fields in the Initialize response will be:

{
  "code": "00000",
  "message": "SUCCESSFUL"
}

3.This however doesn’t indicate that the transaction itself is successful, you need to pay attention to the Status field of the data object in your API response for the final transaction status.

4.Default status returned is INITIAL


Step 2: Verify/Authorize Transaction

Step 2a : Request for the wallet pin from your customer. This is the unique ID used by the customer to authenticate transactions on his/her OPay app.

Step 2b : Specify the API url for the VerifyPIN API and arrange the headers using the API credentials fetched from your dashboard (header format is as specified below).

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/verifyPIN

Sample Request

post/certpay/verifyPIN
curl -X POST --header 'Authorization: Bearer public_key'
--header 'MerchantId: 256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/verifyPIN

Step 2c : Retrieve the OrderNo and ReferenceID returned in Step1c, arrange your request payload (which also includes the customers’ wallet number & specified pin) then call the VerifyPIN API to verify the customers’ OPay pin.

Sample Request Body

post/certpay/verifyPIN
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "userPhone": "+2341234567890",
  "pin": "123456"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
userPhoneUser's mobile phone number. e.g. +2349876543210
pin

Sample Response

post/certpay/verifyPIN
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "status": "PENDING",
  "payMethods": [
    {
      "BALANCE": "available"
    },
    {
      "SAVING": "unavailable"
    }
  ]
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number from OPay payment
statusPIN_VERIFIED (PIN verified)
PIN_WRONG (PIN wrong).
payMethodsPayment method present when status=PIN_VERIFIED
BALANCE (Balance payment): available
SAVING (OWealth): unavailable.

Things To Note

  1. Default Status returned for successfully verified pin is PENDING.

  2. Types of wallets customer has profiled would be returned in the API response i.e.

 "payMethods": [
      {
          "BALANCE": "available"
      },
      {
          "SAVING": "unavailable"
      }
  ]

Step 3: Request for OTP generation

Despite verifying the transaction with their wallet pin, your customers still need to authenticate the payment transaction using an OTP that will be uniquely generated for them by OPay. Kindly note that OTP generation isn’t automatic and you have to request for this by calling the SendOTP API.

Step 3a : Display available wallets (payMethod) to your customer to select from.

Step 3b : Specify the API url for the SendOTP API and arrange the headers using the API credentials fetched from your dashboard (header format is as specified below).

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/sendOTP

post/certpay/sendOTP
curl -X POST --header 'Authorization: Bearer public_key'
--header 'MerchantId: 256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/sendOTP

Step 3c : Retrieve the OrderNo and ReferenceID returned in Step1c, arrange your request payload (which also includes the customers’ selected wallet type) then call the SendOTP API to instruct OPay to generate an OTP and send to the users’ mobile number.

Sample Request Body

post/certpay/sendOTP
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "payMethod": "BALANCE"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
payMethodPayment method user selected

Sample Response

post/certpay/sendOTP
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "status": "OTP_SENT"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
statusOTP_SENT

NOTE : Default Status returned for successfully generated OTP is OTP_SENT


Step 4: Verify OTP

Request that your customers check the mobile number linked to their OPay wallet for the OTP that was sent to them via SMS and specify it on your payment page. This will then be forwarded to OPay via the VerifyOTP API for verification passing the OTP, wallet type, OrderNo and ReferenceID returned in Step1c .

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/verifyOTP

Sample Request

post/certpay/verifyOTP
curl -X POST --header 'Authorization: Bearer public_key' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/verifyOTP

Sample Request Body

post/certpay/verifyOTP
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "otp": "123456",
  "payMethod": "BALANCE"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
otpOTP submitted by user
payMethodPayment method user selected

Sample Response

post/certpay/verifyOTP
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "amount": "10000",
  "currency": "NGN",
  "userPhone": "+2349876543210",
  "status": "PENDING"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
amountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
userPhoneUser phone number sent by merchant
statusOTP_WRONG
PENDING
SUCCESSFUL
FAILED
CLOSED

Step 5: Verify Status

Verify the status of the transaction by calling the Status API passing the OrderNo and ReferenceID returned in Step1c. Ensure that a SUCCESS status is returned before assigning value to the customer on your platform.

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/status

Sample Request

post/certpay/status
curl -X POST --header 'Authorization: Bearer Signature' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/status

Sample Request Body

post/certpay/status
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment

Sample Response

post/certpay/status
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "userPhone": "xxx",
  "amount": "100",
  "currency": "NGN",
  "status": "INITIAL"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
amountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
statusINITIAL
PENDING
SUCCESSFUL
FAILED
CLOSED

Close a transaction

Description

Close a transaction to prevent duplicated or invalid payment.

Valid was raised with an header Authorization: Bearer Signature which is essentially a HMAC SHA512 signature of the whole payload signed using your Secret Key , and payload should be ordered by keys in alphabetical order.

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/close

Sample Request

post/certpay/close
curl -X POST --header 'Authorization: Bearer Signature' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/close

Sample Request Body

post/certpay/close
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982"
}
RESPONSE PROPERTYDESCRIPTION
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment

Sample Response

post/certpay/close
{
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "status": "INITIAL"
}
RESPONSE PROPERTYDESCRIPTION
orderNoOrder number from OPay payment
referenceOrder number of merchant (unique order number from merchant platform)
statusCLOSED

Refund a transaction

Description

Refund a transaction.

Please note that the Authorization header consists of “Bearer Signature” which is essentially a HMAC SHA512 signature of the whole payload (arranged in alphabetical order) signed using your Secret Key. You can use our Signature calculator here.

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/refund

Sample Request

post/certpay/refund
curl -X POST --header 'Authorization: Bearer Signature' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/refund

Sample Request Body

post/certpay/refund
{
  "refundReference": "rf_test_20191123132233",
  "reference": "test_20191123132233",
  "orderNo": "20019212912901281821982",
  "refundAmount": "10000",
  "currency": "NGN"
}
RESPONSE PROPERTYDESCRIPTION
refundReferenceRefund order number of merchant (unique refund order number from merchant platform)
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
refundAmountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN

Sample Response

post/certpay/refund
{
  "refundReference": "rf_test_20191123132233",
  "reference": "test_20191123132233",
  "refundOrderNo": "30019212912901281821982",
  "orderNo": "20019212912901281821982",
  "refundAmount": "10000",
  "currency": "NGN",
  "refundStatus": "SUCCESSFUL"
}
RESPONSE PROPERTYDESCRIPTION
refundReferenceRefund order number of merchant (unique refund order number from merchant platform)
referenceOrder number of merchant (unique order number from merchant platform)
refundOrderNoRefund Order number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
refundAmountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
refundStatusSUCCESSFUL

Refund Status of a transaction

Description

Enquiry into a refund transaction status.

When you get PENDING as a status or if there was an exception when calling any of the certpay endpoints, wait 10 seconds or more, then make a check to see if its status has changed. Don't call too early as you may get a lot more pending than you should.

Please note that the Authorization header consists of “Bearer Signature” which is essentially a HMAC SHA512 signature of the whole payload (arranged in alphabetical order) signed using your Secret Key. You can use our Signature calculator here.

HTTP Method

POST

Sandbox
http://sandbox-cashierapi.opayweb.com/api/v3
Production
https://cashierapi.opayweb.com/api/v3

API Endpoint

/certpay/refundStatus

Sample Request

post/certpay/refundStatus
curl -X POST --header 'Authorization: Bearer Signature' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/certpay/refundStatus

Sample Request Body

post/certpay/refundStatus
{
  "refundReference": "rf_test_20191123132233",
  "reference": "test_20191123132233",
  "refundOrderNo": "30019212912901281821982",
  "orderNo": "20019212912901281821982"
}
RESPONSE PROPERTYDESCRIPTION
refundReferenceRefund order number of merchant (unique refund order number from merchant platform)
referenceOrder number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
refundOrderNoRefund Order number of merchant (unique order number from merchant platform)

Sample Response

post/certpay/refundStatus
{
  "refundReference": "rf_test_20191123132233",
  "reference": "test_20191123132233",
  "refundOrderNo": "30019212912901281821982",
  "orderNo": "20019212912901281821982",
  "refundAmount": "100",
  "currency": "NGN",
  "refundStatus": "SUCCESSFUL"
}
RESPONSE PROPERTYDESCRIPTION
refundReferenceRefund order number of merchant (unique refund order number from merchant platform)
referenceOrder number of merchant (unique order number from merchant platform)
refundOrderNoRefund Order number of merchant (unique order number from merchant platform)
orderNoOrder number of OPay payment
refundAmountAmount in kobo
currencyCurrency charge should be performed in. Default is NGN
refundStatusINITIAL
PENDING
SUCCESSFUL
CLOSED

CONTENTS

  • Community

  • Official Website
  • Facebook
  • Linkedln
  • Twitter
Was this page helpful?
Yes
No

Help us make this page better

Please leave a comment on how we can improve your experience.