OPay Wallet Payment

This endpoint allows you to implement OPay Wallet as an additional payment option on your platform.


Initialize payment

Description

Initialize a Certification Payment transaction.

HTTP Method

POST

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

API Endpoint

/walletpay/initialize

Sample Request

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

Sample Request Body

post/walletpay/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/walletpay/initialize
{
  "orderNo": "20019212912901281821982",
  "reference": "test_20191123132233",
  "amount": "100",
  "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

Verify PIN

Description

Verify OPay user's PIN.

HTTP Method

POST

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

API Endpoint

/walletpay/verifyPIN

Sample Request

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

Sample Request Body

post/walletpay/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/walletpay/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 (OWelath): unavailable.

SendOTP

Description

Send OTP to user's mobile.

HTTP Method

POST

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

API Endpoint

/walletpay/sendOTP

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

Sample Request Body

post/walletpay/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/walletpay/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

VerifyOTP

Description

Submit OTP to complete transaction.

HTTP Method

POST

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

API Endpoint

/walletpay/verifyOTP

Sample Request

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

Sample Request Body

post/walletpay/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/walletpay/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

Status

Description

When you get "PENDING" as a status or if there was an exception when calling any of the walletpay 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.

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

/walletpay/status

Sample Request

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

Sample Request Body

post/walletpay/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/walletpay/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

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

/walletpay/close

Sample Request

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

Sample Request Body

post/walletpay/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/walletpay/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

Description

Refund a transaction.

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

/walletpay/refund

Sample Request

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

Sample Request Body

post/walletpay/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/walletpay/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

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

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

/walletpay/refundStatus

Sample Request

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

Sample Request Body

post/walletpay/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/walletpay/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
  • 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.