Betting/Airtime Topup

OPay allows merchants to topup their customers' betting balance via API.

Basic flow:

For betting

Call /api/v3/bills/betting-providers to get all the avaliable betting service providers.
Call /api/v3/bills/validate to validate the beneficiary account(customerId) with a specific betting provider.
Call /api/v3/bills/bulk-bills to initialize topup transactions. batch topup is also supported.
Call /api/v3/bills/status to inquire the latest or final transaction status.

For airtime

Call /api/v3/bills/bulk-bills to initiate topup transactions. Batch topup is also supported.
Call /api/v3/bills/status to inquire the latest or final transaction status.

/bills/betting-providers

HTTP Method

POST

Sandbox

http://sandbox-cashierapi.opayweb.com/api/v3

Production

https://cashierapi.opayweb.com/api/v3

API Endpoint

/bills/betting-providers

Sample Request

post/bills/betting-providers

curl -X POST --header 'Authorization: Bearer PUBLIC_KEY' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/bills/betting-providers

Sample Response

post/bills/betting-providers

[
  {
    "provider": "NAIRABET",
    "providerLogoUrl": "https://owallet-prod-public.oss-eu-west-1.aliyuncs.com/images/api/icon/betting/nairabet.png",
    "minAmount": {
      "currency": "NGN",
      "amount": 10000
    },
    "maxAmount": {
      "currency": "NGN",
      "amount": 10000000
    }
  },
  {
    "provider": "BET9JA",
    "providerLogoUrl": "https://owallet-prod-public.oss-eu-west-1.aliyuncs.com/images/api/icon/betting/Bet9ja.png",
    "minAmount": {
      "currency": "NGN",
      "amount": 10000
    },
    "maxAmount": {
      "currency": "NGN",
      "amount": 10000000
    }
  }
]

RESPONSE PROPERTY	DESCRIPTION
provider	OBetting topup service provider
providerLogoUrl	Provider logo URL
minAmount	amount in `kobo`. The minimum limit for a single transaction, if it is not returned, it means there is no limit
maxAmount	amount in `kobo`. The maximum limit for a single transaction, if it is not returned, it means there is no limit

/bills/validate

Validate the customerId for a specific provider.

HTTP Method

POST

Sandbox

http://sandbox-cashierapi.opayweb.com/api/v3

Production

https://cashierapi.opayweb.com/api/v3

API Endpoint

/bills/validate

Sample Request

post/bills/validate


curl -X POST --header 'Authorization: Bearer PUBLIC_KEY' --header 'MerchantId:
256619092316009' --header 'content-type: application/json'
https://cashierapi.opayweb.com/api/v3/bills/validate

Sample Request Body

post/bills/validate

{
  "serviceType": "betting",
  "provider": "NAIRABET",
  "customerId": "20019212912901281821982"
}

REQUEST PROPERTY	DESCRIPTION
serviceType	betting
provider	provider returned in betting-providers
customerId	beneficiary's customerId for the specific provider

Sample Response

post/bills/validate

{
  "provider": "NAIRABET",
  "customerId": "20019212912901281821982",
  "firstName": "xxx",
  "lastName": "xxx",
  "userName": "xxx"
}

RESPONSE PROPERTY	DESCRIPTION
provider	provider
customerId	beneficiary's customerId for the specific provider
firstName	returned by provider
lastName	returned by provider
userName	returned by provider

/bills/bulk-bills

Initiate a betting/airtime topup transaction

Valid was raised with an header Authorization: Bear 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

/bills/bulk-bills

Sample Request

post/bills/bulk-bills

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

Sample Request Body

post/bills/bulk-bills

{
  "bulkData": [
    {
      "amount": "1000100",
      "country": "NG",
      "currency": "NGN",
      "customerId": "014562021",
      "provider": "NAIRABET",
      "reference": "123333330001"
    },
    {
      "amount": "10200",
      "country": "NG",
      "currency": "NGN",
      "customerId": "014562021",
      "provider": "NAIRABET",
      "reference": "123333330002"
    }
  ],
  "callBackUrl": "xxxxxx",
  "serviceType": "betting"
}

REQUEST PROPERTY	DESCRIPTION
callBackUrl	Callback Url for successful transaction notification
serviceType	ServiceType for topup, could be betting, airtime
country	Default is NG
currency	Default is NGN
amount	Amount in `kobo`
customerId	For betting, beneficiary's customerId for the specific provider For aitime, it's the benificiary's phone number, e.g.: +2348888899999
provider	For betting, please use the provider returned in betting-providers For airtime, provider could be one of AIR，MTN，GLO，ETI
reference	Order number of merchant (unique order number from merchant platform)

Sample Response

post/bills/bulk-bills

[
  {
    "orderNo": "20019212912901281821981",
    "reference": "test_20191123132232",
    "status": "SUCCESS",
    "errorMsg": ""
  },
  {
    "orderNo": "20019212912901281821982",
    "reference": "test_20191123132233",
    "status": "FAIL",
    "errorMsg": "fail reasons"
  }
]

RESPONSE PROPERTY	DESCRIPTION
orderNo	Order number of OPay payment
reference	Merchant reference (unique order number from merchant platform)
status	INITIAL PENDING SUCCESS FAIL
errorMsg	Will return why error happened

/bills/bulk-status

Initialize a betting topup transaction status inquiry

HTTP Method

POST

Sandbox

http://sandbox-cashierapi.opayweb.com/api/v3

Production

https://cashierapi.opayweb.com/api/v3

API Endpoint

/bills/bulk-status

Sample Request

post/bills/bulk-status

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

Sample Request Body

post/bills/bulk-status

{
  "bulkStatusRequest": [
    {
      "orderNo": "20019212912901281821982",
      "reference": "test_20191123132233"
    },
    {
      "orderNo": "20019212912901281821983",
      "reference": "test_20191123132234"
    },
    {
      "orderNo": "20019212912901281821984",
      "reference": "test_20191123132235"
    }
  ],
  "serviceType": "betting"
}

REQUEST PROPERTY	DESCRIPTION
serviceType	ServiceType for topup, could be betting, airtime
orderNo	Order number of OPay payment (Optional)
reference	Merchant reference (unique order number from merchant platform)

Sample Response

post/bills/bulk-status

[
  {
    "orderNo": "20019212912901281821982",
    "reference": "test_20191123132233",
    "status": "SUCCESS",
    "errorMsg": ""
  },
  {
    "orderNo": "20019212912901281821983",
    "reference": "test_20191123132234",
    "status": "FAIL",
    "errorMsg": "error"
  },
  {
    "orderNo": "20019212912901281821983",
    "reference": "test_20191123132234",
    "status": null,
    "errorMsg": "order does not exist!"
  }
]

RESPONSE PROPERTY	DESCRIPTION
orderNo	Order number of OPay payment
reference	Merchant reference (unique order number from merchant platform)
status	INITIAL PENDING SUCCESS FAIL
errorMsg	error message

/bills/betting-providers
/bills/validate
/bills/bulk-bills
/bills/bulk-status