Remittances

Welcome to the OPay Remittance developer documentation hub! As an MTO, you’ll find here comprehensive API specifications to assist you with integrating our remittance services which will enable you connect international money senders and receivers.


Remittance Authorization API

We require you to authenticate all of your requests with OAuth. Thus, you need to include your token in the Authorization header of each request made.


We share a secret and public key with each merchant. This will enable you to generate your access code and access token. The public key is your identifier while your secret key should not be shared with anyone and kept secure. If for any reason you think your secret key has been compromised, please reach out to us to change your key.


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

Access Code

This API takes in the public key as an input and generates an access code which can be used to generate an access token.

Sample Request

post/api/access/code
curl -X POST --header 'content-type: application/json' -d '{"publicKey":
"OPAY2334302012434320.45234521534553443"}' https://opayweb.com/api/access/code

Sample Request Body

post/api/access/code
{
  "publicKey": "OPAY2334302012434320.45234521534553443"
}
REQUEST PROPERTYDESCRIPTION
publicKeyMerchant's public key

Sample Response

post/api/access/code
{
  "data": {
    "accessCode": "08f765343da454562a9451fb2bc16c1be"
  }
}
RESPONSE PROPERTYDESCRIPTION
data.accessCodeGet the code required for the second token

Access Token

This API takes in the private key and the generated access code. Please note that the access code is valid for 1 hour.

Sample Request

post/api/access/token
curl -X POST --header 'content-type: application/json' -d '{"privateKey":
"OPAY32443432340541540.3456345645665444","accessCode":
"a1c654gdfger405e454ee1cd9f0e09f"}' https://opayweb.com/api/access/token

Sample Request Body

post/api/access/token
{
  "privateKey": "OPAY32443432340541540.3456345645665444",
  "accessCode": "a1c654gdfger405e454ee1cd9f0e09f"
}
REQUEST PROPERTYDESCRIPTION
privateKeyMerchant's privateKey key
accessCodeThe first step uses the code obtained by the public key

Sample Response

post/api/access/token
{
  "data": {
    "accessToken": {
      "value": "eyJdfUzIffdiJ9.eyJqdGkiOiJPUEFZUFJgsdfasczMjAyMDEyfdsjI0MjQwNDQwMzY0NjQ0IiwiaXNzIjoiMSIsImV4cCI6MTYwMDI1ODk1NX0.lkaaDfdsk8JomHfdsfpOdqgV0o8xL1oYWmawddyQ",
      "expires_in": "1h0m0s"
    }
  }
}
RESPONSE PROPERTYDESCRIPTION
data.accessToken.valueToken value required by the endpoint
data.accessToken.expires_inToken Expiration

Remittance API

This API is used to allow MTO merchants to make payments to various external customers either to their wallet or bank on behalf of a customer/sender. The API requires the MTO merchant to provide the sender and the receiver details. This API is only available to merchants registered with the remittance service enabled. Please contact us to get your merchant account enabled with the remittance service.

Lookup Banks

Sample Request

post/api/lookup/banks
curl -X POST --header 'content-type: application/json' --header 'Authorization: Bearer Token' -d
'{"countryCode": "NG"}' https://opayweb.com/api/lookup/banks

Sample Request Body

post/api/lookup/banks
{
  "countryCode": "NG"
}
REQUEST PROPERTYDESCRIPTION
countryCodecountry code

Sample Response

post/api/lookup/banks
{
  "data": {
    "banks": [
      {
        "type": "Advans La Fayette",
        "name": "Advans La Fayette",
        "code": "195"
      },
      {
        "type": "alat",
        "name": "Alat By Wema",
        "code": "035"
      },
      {
        "type": "AssetMatrix MFB",
        "name": "AssetMatrix MFB",
        "code": "404"
      },
      {
        "type": "Cellulant",
        "name": "Cellulant",
        "code": "105"
      },
      {
        "type": "Contec Global",
        "name": "Contec Global",
        "code": "132"
      },
      {
        "type": "diamondBank",
        "name": "Diamond Bank",
        "code": "063"
      },
      {
        "type": "Eartholeum",
        "name": "Eartholeum",
        "code": "121"
      },
      {
        "type": "ecoMobileBank",
        "name": "Ecobank Mobile",
        "code": "307"
      }
    ]
  }
}
RESPONSE PROPERTYDESCRIPTION
data.banks.typeBank type
data.banks.nameBank name
data.banks.codeBank code, Bank unique code

Remittance Bank

This API allows an MTO merchant to make payment to a receiver's bank on behalf of a sender. This API is only available to merchants registered with the remittance service enabled. Please contact us to get your merchant account enabled with the remittance service.

The API requires the MTO merchant to provide sender and receiver details. Please note that these details can be rejected on certain criteria. See the status codes below for error cases.


Note
If the nameCheck field has a value of no, the receiver's name is disregarded and the funds are sent to the account number inputted. If the value is yes, the names are matched exactly with the receiver's bank account name.

Sample Request

post/api/remittances/bank
curl -X POST --header 'content-type: application/json' --header 'Authorization: Bearer Token' -d
'{"remittanceInput":{"amount":"1000","currency":"NGN","narration":"test","purpose":"test",
"receiver":{"country":"NG","name":"Andy Liu","phoneNumber":"+2347015554444","nameCheck":"no"},
"reference":"dfsdfasf3443434","remittanceInfo":{"amount":"1000","exchangeRate":"1000","fees":"1000",
"senderCurrency":"1000"},
"sender":{"name":"Abudula","city":"Lagos","country":"NG","phoneNumber":"+2347014562023"},"isCredit":"N"}}'
https://opayweb.com/api/remittances/bank

Sample Request Body

post/api/remittances/bank
{
  "remittanceInput": {
    "amount": "1000",
    "currency": "NGN",
    "narration": "Payment made towards airtime bill for Kamil",
    "purpose": "maintenance",
    "receiver": {
      "name": "Test Bank Account",
      "nameCheck": "no",
      "phoneNumber": "+2348144234543",
      "country": "NG",
      "bankCode": "044",
      "bankAccountNumber": "1234567890"
    },
    "reference": "dashtop_2423r23423424",
    "remittanceInfo": {
      "amount": "1000",
      "exchangeRate": "1 CAD = 277.59 NGN",
      "fees": "1000",
      "senderCurrency": "CAD"
    },
    "sender": {
      "name": "Alice Jane",
      "city": "Ontario",
      "country": "CA",
      "phoneNumber": "+2347014562023"
    },
    "isCredit": "N"
  }
}
REQUEST PROPERTYDESCRIPTION
remittanceInput.amountAmount to bank in NGN
remittanceInput.currencyCurrency charge should be performed in.
Default is NGN
remittanceInput.narrationTransaction postscript
remittanceInput.purposeTransaction purpose
remittanceInput.receiver.countryReceiver's country
remittanceInput.receiver.nameReceiver's name
remittanceInput.receiver.phoneNumberReceiver's phoneNumber
remittanceInput.receiver.bankCodeReceiver's bankCode
remittanceInput.receiver.bankAccountNumberReceiver's bankAccountNumber
remittanceInput.receiver.nameCheckReceiver's nameCheck
remittanceInput.remittanceInfo.amountamount
remittanceInput.remittanceInfo.exchangeRateExchange rate
remittanceInput.remittanceInfo.feesFees
remittanceInput.remittanceInfo.senderCurrencyCurrency
remittanceInput.sender.nameSender's name
remittanceInput.sender.citySender's city
remittanceInput.sender.countrySender's country
remittanceInput.sender.phoneNumberSender's phone number
remittanceInput.isCreditOPay credit, need to open permissions

Sample Response

post/api/remittances/bank
{
  "data": {
    "remittancesWallet": {
      "amount": "1000",
      "currency": "NGN",
      "failure_reason": "",
      "status": "successful",
      "status_description": "",
      "transaction_id": "20090232323434234343",
      "reference": ""
    }
  }
}
RESPONSE PROPERTYDESCRIPTION
data.remittancesWallet.amountAmount to bank in NGN
data.remittancesWallet.currencyCurrency charge should be performed in. Default is NGN
data.remittancesWallet.failure_reasonReason for failure
data.remittancesWallet.statusTransaction status,eg: successful, processing, failed
data.remittancesWallet.status_descriptionDescription for status
data.remittancesWallet.transaction_idTransaction Number
data.remittancesWallet.referenceTransaction reference

Remittance Wallet

This API allows an MTO merchant to make payment to a receiver's OPay wallet on behalf of a sender. The API requires the MTO merchant to provide sender and receiver OPay account details. Please note that these details can be rejected on certain criteria. See the status codes below for error cases.

Note
These details can be rejected on certain criteria.

Sample Request

post/api/remittances/wallet
curl -X POST --header 'content-type: application/json' --header 'Authorization: Bearer Token' -d
'{"remittanceInput":{"amount":"1000","currency":"NGN","narration":"test","purpose":"test","receiver"
:{"country":"NG","name":"Andy Liu","phoneNumber":"+2347015554444","nameCheck":"no"},"reference":"dfsdfasf3443434",
"remittanceInfo":{"amount":"1000","exchangeRate":"1000","fees":"1000","senderCurrency":"1000"},
"sender":{"name":"Abudula","city":"Lagos","country":"NG","phoneNumber":"+2347014562023"},"isCredit":"N"}}
' https://opayweb.com/api/remittances/wallet

Sample Request Body

post/api/remittances/wallet
{
  "remittanceInput": {
    "amount": "1000",
    "currency": "NGN",
    "narration": "Payment made towards airtime bill for Kamil",
    "purpose": "maintenance",
    "receiver": {
      "country": "NG",
      "name": "Andy Liu",
      "phoneNumber": "+2347015554444"
    },
    "reference": "dashtop_2423r23423424",
    "nameCheck": "no",
    "remittanceInfo": {
      "senderCurrency": "CAD",
      "exchangeRate": "1 CAD = 277.59 NGN",
      "amount": 4000,
      "fees": 40
    },
    "sender": {
      "name": "Abudula",
      "city": "Lagos",
      "country": "NG",
      "phoneNumber": "+2347014562023"
    },
    "isCredit": "N"
  }
}
REQUEST PROPERTYDESCRIPTION
remittanceInput.amountAmount to bank in NGN
remittanceInput.currencyCurrency charge should be performed in.
Default is NGN
remittanceInput.narrationTransaction postscript
remittanceInput.purposeTransaction purpose
remittanceInput.receiver.countryReceiver's country
remittanceInput.receiver.nameReceiver's name
remittanceInput.receiver.phoneNumberReceiver's phoneNumber
remittanceInput.remittanceInfo.amountamount
remittanceInput.remittanceInfo.exchangeRateExchange rate
remittanceInput.remittanceInfo.feesFees
remittanceInput.remittanceInfo.senderCurrencyCurrency
remittanceInput.sender.nameSender's name
remittanceInput.sender.citySender's city
remittanceInput.sender.countrySender's country
remittanceInput.sender.phoneNumberSender's phoneNumber
remittanceInput.isCreditOPay credit, need to open permissions

Sample Response

post/api/remittances/wallet
{
  "data": {
    "remittancesWallet": {
      "amount": "1000",
      "currency": "NGN",
      "failure_reason": "",
      "status": "successful",
      "status_description": "",
      "transaction_id": "20090232323434234343",
      "reference": ""
    }
  }
}
RESPONSE PROPERTYDESCRIPTION
data.remittancesWallet.amountAmount to bank in NGN
data.remittancesWallet.currencyCurrency charge should be performed in. Default is NGN
data.remittancesWallet.failure_reasonReason for failure
data.remittancesWallet.statusTransaction status,eg: successful, processing, failed
data.remittancesWallet.status_descriptionDescription for status
data.remittancesWallet.transaction_idTransaction Number
data.remittancesWallet.referenceTransaction reference

Remittance Transaction Status

This API returns the status of the payment made via bank or wallet transfer. Payment made can be in the following state:

  1. Completed: The payment has been completed and successfully money transferred into receiver wallet.
  2. Pending: The payment has been credited from merchant wallet but pending claim by receiver. This can be due to the fact that the receiver is yet to onboard or fulfill KYC requirements or network issues with the recipient bank.
  3. Failed: The payment failed due to either name mismatch or insufficient balance.


Sample Request

post/api/remittances/{id}
 -X POST --header 'Authorization: Bearer
 eyJhbGciOiJIUzI1NiJ9.eyJqfdsfgJPUEFZUFgsdf434MDEyMjAuNjI0MjQwNDQwMzY0NjQ0Iiw
 iaXNzIjogfdsgsd5464wMDI1OTAxN30.u2RQ7M5QKqE0Wke3vl08zHfdsg65315ONluwY'
 https://opayweb.com/api/remittances/20093232323234354334

Sample Response

post/api/remittances/{id}
{
  "data": {
    "order": {
      "close_reason": "",
      "closed": false,
      "failed": false,
      "failure_reason": "",
      "id": "5aea823451d2da4de41de0cb",
      "type": "Complete"
    }
  }
}
RESPONSE PROPERTYDESCRIPTION
data.order.close_reasonReason for closing the order
data.order.closedWhether the order is closed
data.order.failedWhether the order failed
data.order.failure_reasonReason for failed order
data.order.idTransaction Number
data.order.typeTransaction Type: Complete, Pending, Failed
  • 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.