Docs

Digital Wallets

OPay "Wallet as A Service" (Digital wallet) is a cutting-edge solution that empowers businesses to integrate digital wallet systems effortlessly, transforming the way you handle financial transactions through employees or affiliated entities.

Key Benefits:

  • Enhanced Security and Speedy Transactions: Funds collected via subordinate digital wallets are directly funnelled into your company's primary account, bypassing the risks associated with cash handling and significantly speeding up the collection process compared to traditional methods.
  • Unmatched Transparency and Visibility: Our platform not only ensures prompt fund transfers but also provides employees and sub-merchants with continuous, real-time access to payment statuses. This level of transparency eliminates the need for cumbersome payment confirmation processes.

Ideal Applications: "Wallet as A Service" is exceptionally beneficial for industries such as FMCG distribution, food and supermarket delivery, logistics, and any business operating on a Cash on Delivery (COD) model or with a multi-tiered merchant structure or network. With OPay WaaS, you can streamline your financial operations and boost efficiency across the board.

Create Digital Wallet

URL: https://payapi.opayweb.com/api/v2/third/depositcode/generateStaticDepositCode

Request Parameters

ParameterTypeRequiredDescription
opayMerchantIdStringYesBranch ID of the Digital Wallet
nameStringYesDigital Wallet holder's name
refIdStringOptional
Digital Wallet holder's Ref ID (15 characters including digits and/or letters).
Creating wallet requires at least one of these three: Ref ID, email address, and Phone number.
emailStringOptional
Digital Wallet holder's email address.
Creating wallet requires at least one of these three: Ref ID, email address, and Phone number.
phoneStringOptional
Digital Wallet holder's phone number.
Creating wallet requires at least one of these three: Ref ID, email address, and Phone number.
accountTypeStringYesCollection account types: If you choose "Merchant", the money collected via this Digital Wallet will be credited directly into the company's OPay account (Business/Branch account); If you choose "User", the money collected via this Digital Wallet will stay in the Digital Wallet, and the company can sweep all the money into its OPay account.
sendPassWordFlagStringNoThis parameter defines the sending of OPay Business APP account credentials for using the Digital Wallet. If you pass Y, or empty, or do not pass any data, OPay will send out the account credentials to the Digital Wallet holders via email or SMS. If you pass N, no emails or SMS will be sent. Make sure you pass Y/N in capital letters.

POST
{
  "opayMerchantId":"256621072768092",
  "refId": "refer1200000850",
  "name": "abc",
  "email":"234432@163.com",
  "phone":"2341231231231",
  "accountType":"Merchant",
  "sendPassWordFlag":"N"
}
1
2
3
4
5
6
7
8
9

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
depositCodeStringDigital Wallet Number
nameStringDigital Wallet holder's name
refIdStringDigital Wallet holder's Ref ID (15 characters including digits and/or letters)
emailOrPhoneStringDigital Wallet holder's email address or phone number
accountTypeStringCollection account types: If you choose "Merchant", the money collected via this Digital Wallet will be credited directly into the company's OPay account (Business/Branch account); If you choose "User", the money collected via this Digital Wallet will stay in the Digital Wallet, and the company can sweep all the money into its OPay account.

POST
{
  "code": "00000",
  "data": {
    "depositCode": "6126390625",
    "name": "aa",
    "refId": "refer1200000850",
    "emailOrPhone": "+2341234567890",
    "accountType": "Merchant"
  },
  "message": "SUCCESSFUL"
}
1
2
3
4
5
6
7
8
9
10
11

Query Wallet Details

URL: https://payapi.opayweb.com/api/v2/third/depositcode/queryStaticDepositCodeInfo

Request Parameters Request Parameters

ParameterTypeRequiredDescription
opayMerchantIdStringYesBranch ID of the Digital Wallet
depositCodeStringYesDigital Wallet Number

POST
{
  "opayMerchantId": "256621072768092",
  "depositCode": "6126390625"
}
1
2
3
4

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
depositCodeStringDigital Wallet Number
nameStringDigital Wallet holder's name
refIdStringDigital Wallet holder's Ref ID (15 characters including digits and/or letters)
emailStringDigital Wallet holder's email address
phoneStringDigital Wallet holder's phone number
createTimeStringDigital Wallet creation time
formatDateTimeStringDigital Wallet creation time (Nigerian time: yyyy-MM-dd HH:mm:ss)
Show more parameters

POST
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "depositCode": "6126390625",
    "name": "aaa",
    "refId": "refer1200000850",
    "email": "234432@163.com",
    "phone": "2341231231231",
    "createTime": 34124243242000,
    "formatDateTime":"2022-09-27 13:34:36",
    "accountType": "Merchant"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Query Transaction History

URL: https://payapi.opayweb.com/api/v2/third/depositcode/queryStaticDepositCodeTransList

Request Parameters

ParameterTypeRequiredDescription
opayMerchantIdStringYesBranch ID of the Digital Wallet
depositCodesList<String>NoDigital Wallet Number - up to 1000
pageNolongYesPage number
pageSizelongYesNumber of transactions in one page - 500 at most
startTimelongNoStart time (in ms)
endTimelongNoEnd time (in ms)

POST
{
  "opayMerchantId": "256621072768092",
  "depositCodes": ["6126390625", "6126390626"],
  "pageNo": 1,
  "pageSize": 10,
  "startTime": 1651334396400,
  "endTime": 1664467200000
}
1
2
3
4
5
6
7
8

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
totallongTotal number of transactions
listlist
list.depositCodeStringDigital Wallet Number
list.merchantIdStringBranch ID of the Digital Wallet
list.orderNoStringReference number of your payment order
list.orderStatusStringTransaction status: SUCCESS, FAIL, PENDING
list.depositTimelongTransaction time
Show more parameters

POST
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "total": 2,
    "list": [
      {
        "merchantId": "256622022480363",
        "depositCode": "6126390625",
        "orderNo": "20220319702512368471543808",
        "depositTime": 1663153219000,
        "depositAmount": "800.00",
        "currency": "NGN",
        "orderStatus":"SUCCESS",
        "formatDateTime":"2022-09-27 13:34:36",
        "transactionId":"20220319702512368471543808",
        "notes":"test"
      },
      {
        "merchantId": "256622022480363",
        "depositCode": "6126390626",
        "orderNo": "20220319702512368471543808",
        "depositTime": 1663153219000,
        "depositAmount": "800.00",
        "currency": "NGN",
        "orderStatus":"SUCCESS",
        "formatDateTime":"2022-09-27 13:34:36",
        "transactionId":"20220319702512368471543808",
        "notes":"test"
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

Query Wallet Balance

URL: https://payapi.opayweb.com/api/v2/third/depositcode/queryWalletBalance

Request Parameters

ParameterTypeRequiredDescription
opayMerchantIdStringYesBranch ID of the Digital Wallet
depositCodeStringYesDigital Wallet Number

POST
{
  "opayMerchantId": "256621072768092",
  "depositCode": "6126390625"
}
1
2
3
4

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
nameStringDigital Wallet holder's name
refIdStringDigital Wallet holder's Ref ID (15 characters including digits and/or letters)
amountStringAmount
currencyStringCurrency
queryTimelongQuery time (Nigerian time: yyyy-mm-dd hh:mm:ss)

POST
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "name": "aaa",
    "refId": "refer1200000850",
    "amount": "234",
    "currency": "NGN",
    "queryTime": "2022-09-29 08:47:55"
  }
}
1
2
3
4
5
6
7
8
9
10
11

Sweep

URL: https://payapi.opayweb.com/api/v2/third/depositcode/transferToMerchant

Request Parameters

ParameterTypeRequiredDescription
amountStringYesSweep amount - the money transferred from Digital Wallet to the company's OPay account (in Naira)
depositCodeStringYesDigital Wallet Number
opayMerchantIdStringYesBranch ID of the Digital Wallet
collectionMerchantIdStringYesBranch ID of the sweep-in account
requestSerialNoStringYesRequest Serial No.
descriptionStringYesSweep description

POST
{
  "amount": "123",
  "depositCode": "6126390625",
  "opayMerchantId":"256621072768092",
  "collectionMerchantId": "256621072768092",
  "requestSerialNo": "2333232322323233",
  "description": "message"
}
1
2
3
4
5
6
7
8

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
orderNoStringSweep order No.
statusStringSweep order status
amountStringSweep amount
currencyStringCurrency
tradeTimeStringTransaction time (Nigerian time: yyyy-MM-dd HH:mm:ss)
errorMessageStringFailure reason

POST
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "orderNo": "2333331231",
    "status": "2333331231",
    "amount": "234",
    "currency": "NGN",
    "tradeTime": "2022-09-29 08:47:55",
    "errorMessage": "order does not exist"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

Query Sweep Status

URL: https://payapi.opayweb.com/api/v2/third/depositcode/queryTransferStatus

Request Parameters

ParameterTypeRequiredDescription
opayMerchantIdStringYesBranch ID of the Digital Wallet
orderNoStringYesSweep order No.
requestSerialNoStringYesRequest Serial no.

POST
{
  "opayMerchantId": "256621072768092",
  "orderNo": "233333423424",
  "requestSerialNo": "2333232322323233"
}
1
2
3
4
5

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
statusStringSweep status
amountStringSweep amount
currencyStringCurrency
errorMessageStringFailure reason

POST
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "status": "2333331231",
    "amount": "234",
    "currency": "NGN",
    "errorMessage": "order does not exist"
  }
}
1
2
3
4
5
6
7
8
9
10

Modify Wallet Details

URL: https://payapi.opayweb.com/api/v2/third/depositcode/updateWallet

Request Parameters

ParameterTypeRequiredDescription
opayMerchantIdStringYesBranch ID of the Digital Wallet
emailStringOptional
Digital Wallet holder's email address
Modifying wallet details require at least one of these two: email address and phone number.
phoneStringOptional
Digital Wallet holder's phone number
Modifying wallet details require at least one of these two: email address and phone number.
nameStringNoDigital Wallet holder's name
depositCodeStringYesDigital Wallet Number
sendPassWordFlagStringNoThis parameter defines the sending of OPay Business APP account credentials for using the Digital Wallet. If you pass Y, or empty, or do not pass any data, OPay will send out the account credentials to the Digital Wallet holders via email or SMS. If you pass N, no emails or SMS will be sent. Make sure you pass Y/N in capital letters.
refIdStringNoYour Reference ID

POST
{
  "opayMerchantId": "256621072768092",
  "email": "321312@163.com",
  "phone":"",
  "name":"xqqtest",
  "depositCode": "6123929200",
  "sendPassWordFlag":"N",
  "refId":"111111"
}
1
2
3
4
5
6
7
8
9

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
depositCodeStringDigital Wallet Number
nameStringDigital Wallet holder's Name
refIdStringDigital Wallet holder's Ref ID (15 characters including digits and/or letters)
emailStringDigital Wallet holder's email address
phoneStringDigital Wallet holder's phone number
createTimeStringDigital Wallet creation time
formatDateTimeStringDigital Wallet creation time (Nigerian time: yyyy-MM-dd HH:mm:ss)
Show more parameters

POST
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "depositCode": "6126390625",
    "name": "xqqtest",
    "refId": "refer1200000850",
    "email": "321312@163.com",
    "phone": "43242432421",
    "createTime": 34124243242000,
    "formatDateTime":"2022-09-27 13:34:36",
    "accountType": "Merchant"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Delete Wallet

URL: https://payapi.opayweb.com/api/v2/third/depositcode/deleteWallet

Request Parameters

ParameterTypeRequiredDescription
opayMerchantIdStringYesBranch ID of the Digital Wallet
depositCodesList<String>NoDigital Wallet Number

POST
{
  "opayMerchantId": "256621072768092",
  "depositCodes": ["6126390625", "6126390626"]
}
1
2
3
4

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString
dataObject
listlist
list.depositCodeStringDigital Wallet Number
list.statusStringStatus of the Digital Wallet, Active/Inactive

POST
{
  "code": "00000",
  "message": "SUCCESSFUL",
  "data": {
    "list": [
      {
        "depositCode": "6126390625",
        "status": "Inactive"
      },
      {
        "depositCode": "6126390626",
        "status": "Inactive"
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Webhook (Payment Notification)

URL: {your.server.baseUrl}/callback

Request Header

ParameterTypeRequiredDescription
Content-TypeStringYes
X-Opay-TranidStringYesTransaction ID
merchantIdStringYesMerchant ID

Request Body Here are the data you will get from OPay's payment notification:

ParameterTypeRequiredDescription
statusStringYesTransaction status: SUCCESS, FAIL, PENDING
transactionIdStringYesTransaction ID
depositCodeStringYesDigital Wallet Number
refIdStringYesDigital Wallet holder's Ref ID
depositTimeStringYesTransaction time
depositAmountStringYesTransaction amount (in Naira)
currencyStringYesCurrency: NGN
errorCodeStringYesError code (for non-SUCCESS transactions)
errorMsgStringYesError message (for non-SUCCESS transactions)
formatDateTimeStringYesTransaction Time (Nigeria time, yyyy-mm-dd hh:mm:ss)
Show more parameters

POST
{
    "status": "SUCCESS",
    "transactionId": "20220319702512368471543808",
    "reference": "220617145660907314088",
    "depositCode": "6126390625",
    "refId": "refer1200000850",
    "currency": "NGN",
    "depositAmount": "800.00",
    "depositTime": "1663153219000",
    "formatDateTime":"2022-09-27 13:34:36",
    "orderNo":"230221010175463341",
    "notes":"test"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "status": "FAIL",
    "transactionId": "20220319702512368471543808",
    "reference": "220617145660907314088",
    "errorCode": "00003",
    "errorMsg": "SYSTEM ERROR"
}
1
2
3
4
5
6
7

Response

ParameterTypeDescription
codeString00000 stands for successful response, otherwise failed
messageString

Last Updated: 3/6/2025, 9:44:45 AM

← General Payment Webhook →