COD Payment API
In this page, you will learn how to use COD Payment APIs.
1.Create COD Payment
To test your Create COD Payment API, you need to request using the POST method in our sandbox environment.
-Here is the request URL:
https://sandboxapi.opaycheckout.com/api/v1/international/payment/create
-Once you have a fully tested payment flow and you are ready for production, use the following production API endpoint URL instead
https://api.opaycheckout.com/api/v1/international/payment/create
-Request Parameters:
- Header: Authorization(API Calls Signature), MerchantId
- Json object containing the transaction information:
Authorization : Bearer {signature}
MerchantId : 256612345678901
{
"amount": {
"currency": "EGP",
"total": 40000
},
"bankcard": {
"cardHolderName": "DAVID",
"cardNumber": "45087*********",
"cvv": "100",
"enable3DS": true,
"expiryMonth": "02",
"expiryYear": "26"
},
"callbackUrl": "https://your-call-back-url",
"country": "EG",
"payMethod": "COD",
"product": {
"description": "dd",
"name": "name"
},
"reference": reference,
"returnUrl": "https://your-return-url",
"shippingAddress": {
"actualWeight": "3.2",
"consigneeAddress": "consigneeAddress Street",
"consigneeCity": "Abaseya",
"consigneeCountry": "EG",
"consigneeName": "consigneeName test",
"consigneePhone": "1234567890",
"consigneeState": "CAIRO",
"consignorAddress": "consignorAddress Street",
"consignorCity": "Abaseya",
"consignorCountry": "EG",
"consignorState": "CAIRO",
"numberOfPackages": 1,
"packageDetails": [
{
"chargedWeight": "3.1",
"height": "3.1",
"length": "3.1",
"packageCount": 1,
"selectedPackageTypeCode": "BOX",
"weight": "5.1",
"width": "6.1"
}
],
"productAmount": 7,
"weightUnitType": "KILOGRAM"
},
"userInfo": {
"userEmail": "customer@email.com",
"userId": "666666",
"userMobile": "201066668888",
"userName": "David"
},
"walletAccount": "01120333337"
}
HTTP POST parameters
-Here is a detailed description for the parameters you need to complete the POST request:
-An example of COD create payment request for is as follows :
class CreateCodPaymentController
{
private $secretkey;
private $merchantId;
private $url;
public function __construct() {
$this->merchantId = '281821120675251';
$this->secretkey = 'OPAYPRV16387******157474';
$this->url = 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/create';
}
public function test(){
$data = [
'amount'=> [
'currency'=> 'EGP',
'total'=> 40000
],
'bankcard'=> [
'cardHolderName'=> 'DAVID',
'cardNumber'=> '45087*********',
'cvv'=> '100',
'enable3DS'=> true,
'expiryMonth'=> '02',
'expiryYear'=> '26'
],
'callbackUrl'=> 'https://your-call-back-url',
'country'=> 'EG',
'payMethod'=> 'COD',
'product'=> [
'description'=> 'dd',
'name'=> 'name'
],
'reference'=> "1647857006801",
'returnUrl'=> 'https://your-return-url',
'shippingAddress'=> [
'actualWeight'=> '3.2',
'consigneeAddress'=> 'consigneeAddress Street',
'consigneeCity'=> 'Abaseya',
'consigneeCountry'=> 'EG',
'consigneeName'=> 'consigneeName test',
'consigneePhone'=> '1234567890',
'consigneeState'=> 'CAIRO',
'consignorAddress'=> 'consignorAddress Street',
'consignorCity'=> 'Abaseya',
'consignorCountry'=> 'EG',
'consignorState'=> 'CAIRO',
'numberOfPackages'=> 1,
'packageDetails'=> [
[
'chargedWeight'=> '3.1',
'height'=> '3.1',
'length'=> '3.1',
'packageCount'=> 1,
'selectedPackageTypeCode'=> 'BOX',
'weight'=> '5.1',
'width'=> '6.1'
]
],
'productAmount'=> 7,
'weightUnitType'=> 'KILOGRAM'
],
'userInfo'=> [
'userEmail'=> 'customer@email.com',
'userId'=> '666666',
'userMobile'=> '201066668888',
'userName'=> 'David'
],
'walletAccount'=> '01120333337'
]
;
$data2 = (string) json_encode($data,JSON_UNESCAPED_SLASHES);
$auth = $this->auth($data2);
$header = ['Content-Type:application/json', 'Authorization:Bearer '. $auth, 'MerchantId:'.$this->merchantId];
$response = $this->http_post($this->url, $header, json_encode($data));
$result = $response?$response:null;
return $result;
}
private function http_post ($url, $header, $data) {
if (!function_exists('curl_init')) {
throw new Exception('php not found curl', 500);
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$response = curl_exec($ch);
$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error=curl_error($ch);
curl_close($ch);
if (200 != $httpStatusCode) {
print_r("invalid httpstatus:{$httpStatusCode} ,response:$response,detail_error:" . $error, $httpStatusCode);
}
return $response;
}
public function auth ( $data ) {
$secretKey = $this->secretkey;
$auth = hash_hmac('sha512', $data, $secretKey);
return $auth;
}
}
const request = require('request');
var sha512 = require('js-sha512');
const formData = {
"amount": {
"currency": "EGP",
"total": 40000
},
"bankcard": {
"cardHolderName": "DAVID",
"cardNumber": "45087*********",
"cvv": "100",
"enable3DS": true,
"expiryMonth": "02",
"expiryYear": "26"
},
"callbackUrl": "https://your-call-back-url",
"country": "EG",
"payMethod": "COD",
"product": {
"description": "dd",
"name": "name"
},
"reference": "1647857006829",
"returnUrl": "https://your-return-url",
"shippingAddress": {
"actualWeight": "3.2",
"consigneeAddress": "consigneeAddress Street",
"consigneeCity": "Abaseya",
"consigneeCountry": "EG",
"consigneeName": "consigneeName test",
"consigneePhone": "1234567890",
"consigneeState": "CAIRO",
"consignorAddress": "consignorAddress Street",
"consignorCity": "Abaseya",
"consignorCountry": "EG",
"consignorState": "CAIRO",
"numberOfPackages": 1,
"packageDetails": [
{
"chargedWeight": "3.1",
"height": "3.1",
"length": "3.1",
"packageCount": 1,
"selectedPackageTypeCode": "BOX",
"weight": "5.1",
"width": "6.1"
}
],
"productAmount": 7,
"weightUnitType": "KILOGRAM"
},
"userInfo": {
"userEmail": "customer@email.com",
"userId": "666666",
"userMobile": "201066668888",
"userName": "David"
},
"walletAccount": "01120333337"
}
;
var privateKey = "OPAYPRV16387******157474"
var hash = sha512.hmac.create(privateKey);
hash.update(JSON.stringify(formData));
hmacsignature = hash.hex();
console.log(hmacsignature)
request({
url: 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/create',
method: 'POST',
headers: {
'MerchantId': '281821120675251',
'Authorization': 'Bearer '+hmacsignature
},
json: true,
body: formData
}, function (error, response, body) {
console.log('body: ')
console.log(body)
}
)
curl --location --request POST 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/create' \
--header 'MerchantId: 281821120675251' \
--header 'Authorization: Bearer eda1ed3090baf34d2e18df3ceae768c43bf70b37f2ed3d7d51882b2a62702e6c5446700ea4565f188e109fc58d7fca449de469aa64d08dc9f4f1ffdd7c2a1133' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": {
"currency": "EGP",
"total": 40000
},
"bankcard": {
"cardHolderName": "DAVID",
"cardNumber": "45087*********",
"cvv": "100",
"enable3DS": true,
"expiryMonth": "02",
"expiryYear": "26"
},
"callbackUrl": "https://your-call-back-url",
"country": "EG",
"payMethod": "COD",
"product": {
"description": "dd",
"name": "name"
},
"reference": 1647843829435,
"returnUrl": "https://your-return-url",
"shippingAddress": {
"actualWeight": "3.2",
"consigneeAddress": "consigneeAddress Street",
"consigneeCity": "Abaseya",
"consigneeCountry": "EG",
"consigneeName": "consigneeName test",
"consigneePhone": "1234567890",
"consigneeState": "CAIRO",
"consignorAddress": "consignorAddress Street",
"consignorCity": "Abaseya",
"consignorCountry": "EG",
"consignorState": "CAIRO",
"numberOfPackages": 1,
"packageDetails": [{
"chargedWeight": "3.1",
"height": "3.1",
"length": "3.1",
"packageCount": 1,
"selectedPackageTypeCode": "BOX",
"weight": "5.1",
"width": "6.1"
}],
"productAmount": 7,
"weightUnitType": "KILOGRAM"
},
"userInfo": {
"userEmail": "user001@xxx.com",
"userId": "userid001",
"userMobile": "9876543210",
"userName": "nick"
},
"walletAccount": "01120333337"
}'
import com.google.gson.Gson;
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.TreeMap;
import java.util.UUID;
public class CreateCodPayment {
private static final String privateKey = "OPAYPRV16387******157474";
private static final String endpoint = "https://sandboxapi.opaycheckout.com";
private static final String merchantId = "281821120675251";
public static void main(String[] args) throws Exception {
String addr = endpoint + "/api/v1/international/payment/create";
Gson gson = new Gson();
TreeMap order = new TreeMap<>();
TreeMap amount = new TreeMap<>();
amount.put("currency","EGP");
amount.put("total",new Integer(40000));
order.put("amount",amount);
TreeMap bankcard = new TreeMap<>();
bankcard.put("cardHolderName","DAVID");
bankcard.put("cardNumber","45087*********");
bankcard.put("cvv","100");
bankcard.put("enable3DS",Boolean.TRUE);
bankcard.put("expiryMonth","02");
bankcard.put("expiryYear","26");
order.put("bankcard",bankcard);
order.put("callbackUrl","https://your-call-back-url.com");
order.put("country","EG");
order.put("payMethod","COD");
TreeMap product = new TreeMap<>();
product.put("name","your product name");
product.put("description","your product description");
order.put("product",product);
order.put("reference", UUID.randomUUID().toString());
order.put("returnUrl","https://your-return-url.com");
TreeMap shippingAddress = new TreeMap<>();
shippingAddress.put("actualWeight","3.2");
shippingAddress.put("consigneeAddress","consigneeAddress Street");
shippingAddress.put("consigneeCity","Abaseya");
shippingAddress.put("consigneeCountry","EG");
shippingAddress.put("consigneeName","consigneeName test");
shippingAddress.put("consigneePhone","1234567890");
shippingAddress.put("consigneeState","CAIRO");
shippingAddress.put("consignorAddress","consignorAddress Street");
shippingAddress.put("consignorCity","Abaseya");
shippingAddress.put("consignorCountry","EG");
shippingAddress.put("consignorState","CAIRO");
shippingAddress.put("numberOfPackages",1);
TreeMap packageDetail = new TreeMap<>();
packageDetail.put("chargedWeight", "3.1");
packageDetail.put("height", "3.1");
packageDetail.put("length", "3.1");
packageDetail.put("packageCount", 1);
packageDetail.put("selectedPackageTypeCode", "BOX");
packageDetail.put("weight", "5.1");
packageDetail.put("width", "6.1");
ArrayList packageDetails = new ArrayList<>();
packageDetails.add(packageDetail);
shippingAddress.put("packageDetails",packageDetails);
shippingAddress.put("productAmount",7);
shippingAddress.put("weightUnitType","KILOGRAM");
order.put("shippingAddress",shippingAddress);
TreeMap userInfo = new TreeMap<>();
userInfo.put("userEmail","customer@email.com");
userInfo.put("userId","666666");
userInfo.put("userMobile","201066668888");
userInfo.put("userName","David");
order.put("userInfo",userInfo);
order.put("walletAccount","01120333337");
String requestBody = gson.toJson(order);
System.out.println("--request:");
System.out.println(requestBody);
String oPaySignature = hmacSHA512(requestBody, privateKey);
System.out.println("--signature:");
System.out.println(oPaySignature);
URL url = new URL(addr);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Authorization", "Bearer "+oPaySignature);
con.setRequestProperty("MerchantId", merchantId);
con.setDoOutput(true);
OutputStream os = con.getOutputStream();
byte[] input = requestBody.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), StandardCharsets.UTF_8));
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println("--response:");
System.out.println(response.toString());
//close your stream and connection
}
public static String hmacSHA512(final String data, final String secureKey) throws Exception{
byte[] bytesKey = secureKey.getBytes();
final SecretKeySpec secretKey = new SecretKeySpec(bytesKey, "HmacSHA512");
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(secretKey);
final byte[] macData = mac.doFinal(data.getBytes());
byte[] hex = new Hex().encode(macData);
return new String(hex, StandardCharsets.UTF_8);
}
}
Create COD Payment Response
-Response Parameters:
the parameters contained in the response received whenever you call payment API as a JSON Object.
{
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"reference": "1647833340875",
"orderNo": "220321148180646777059",
"nextAction": {
"actionType": "PICKUP"
},
"status": "PENDING",
"amount": {
"total": 40000,
"currency": "EGP"
},
"vat": {
"total": 0,
"currency": "EGP"
}
}
}
-Here is a detailed description for the parameters received in the response:
| Parameter | type | Description | example | |
|---|---|---|---|---|
| reference | String |
Unique merchant payment order number. | 937102167 | |
| orderNo | String |
Unique Opay payment order number. | 211004140885521681 | |
| status | enum |
[INITIAL, PENDING, SUCCESS, FAIL, CLOSE] | SUCCESS | |
| nextAction | ||||
| actionType | String |
Next action type, enum[PICKUP] | PICKUP | |
| amount | ||||
| total | Integer |
amount(cent unit). | 400 | |
| currency | String |
currency type.See full list here | EGP | |
| vat | ||||
| total | Integer |
amount(cent unit). | 10 | |
| currency | String |
currency type.See full list here | EGP | |
| failureCode | String |
fail error code. | payment fail error code, not blank when status [FAIL/CLOSE] | |
| failureReason | String |
fail error message. | payment fail error message, not blank when status [FAIL/CLOSE] | |
2.Pickup Goods
To test your Pickup Goods Payment, you need to request using the POST method in our sandbox environment.
-Here is the request URL:
https://sandboxapi.opaycheckout.com/api/v1/international/payment/pickup
-Once you have a fully tested payment flow and you are ready for production, use the following production API endpoint URL instead
https://api.opaycheckout.com/api/v1/international/payment/pickup
-Request Parameters:
- Header: Authorization(API Calls Signature), MerchantId
- Json object containing the transaction information:
Authorization : Bearer {signature}
MerchantId : 256612345678901
{
"country": "EG",
"orderNo": "220321148180646777059",
"pickUpDate": "2012-01-01",
"pickUpEndTime": "10:22:22",
"pickUpReadyTime": "12:12:12"
}
HTTP POST parameters
-Here is a detailed description for the parameters you need to complete the POST request:
-An example of Pickup Goods payment request is as follows :
class PickupGoodsController
{
private $secretkey;
private $merchantId;
private $url;
public function __construct() {
$this->merchantId = '281821120675251';
$this->secretkey = 'OPAYPRV16387******157474';
$this->url = 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/pickup';
}
public function test(){
$data = [
'country'=> 'EG',
'orderNo'=> '220321148180647543924',
'pickUpDate'=> '2012-01-01',
'pickUpEndTime'=> '10:22:22',
'pickUpReadyTime'=> '12:12:12'
]
;
$data2 = (string) json_encode($data,JSON_UNESCAPED_SLASHES);
$auth = $this->auth($data2);
$header = ['Content-Type:application/json', 'Authorization:Bearer '. $auth, 'MerchantId:'.$this->merchantId];
$response = $this->http_post($this->url, $header, json_encode($data));
$result = $response?$response:null;
return $result;
}
private function http_post ($url, $header, $data) {
if (!function_exists('curl_init')) {
throw new Exception('php not found curl', 500);
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$response = curl_exec($ch);
$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error=curl_error($ch);
curl_close($ch);
if (200 != $httpStatusCode) {
print_r("invalid httpstatus:{$httpStatusCode} ,response:$response,detail_error:" . $error, $httpStatusCode);
}
return $response;
}
public function auth ( $data ) {
$secretKey = $this->secretkey;
$auth = hash_hmac('sha512', $data, $secretKey);
return $auth;
}
}
const request = require('request');
var sha512 = require('js-sha512');
const formData = {
"country": "EG",
"orderNo": "220321148180647550879",
"pickUpDate": "2012-01-01",
"pickUpEndTime": "10:22:22",
"pickUpReadyTime": "12:12:12"
}
;
var privateKey = "OPAYPRV16387******157474"
var hash = sha512.hmac.create(privateKey);
hash.update(JSON.stringify(formData));
hmacsignature = hash.hex();
console.log(hmacsignature)
request({
url: 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/pickup',
method: 'POST',
headers: {
'MerchantId': '281821120675251',
'Authorization': 'Bearer '+hmacsignature
},
json: true,
body: formData
}, function (error, response, body) {
console.log('body: ')
console.log(body)
}
)
curl --location --request POST 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/pickup' \
--header 'MerchantId: 281821120675251' \
--header 'Authorization: Bearer dc716fff2092d5339fb7850d8b94c22d0a2ce3b343a4ad7c7643d614e91a255c2816e5466e9d2c4124e76e1cf8596f9e8f16520c35ec4cb31fcdf185b20d4822' \
--header 'Content-Type: application/json' \
--data-raw '{
"country": "EG",
"orderNo": "220321148180646907439",
"pickUpDate": "2012-01-01",
"pickUpEndTime": "10:22:22",
"pickUpReadyTime": "12:12:12"
}'
import com.google.gson.Gson;
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.TreeMap;
public class PickUpGoods {
private static final String privateKey = "OPAYPRV16387******157474";
private static final String endpoint = "https://sandboxapi.opaycheckout.com";
private static final String merchantId = "281821120675251";
public static void main(String[] args) throws Exception {
String addr = endpoint + "/api/v1/international/payment/pickup";
Gson gson = new Gson();
TreeMap order = new TreeMap<>();
order.put("country","EG");
order.put("orderNo","220321148180646953669");
order.put("pickUpDate","2012-01-01");
order.put("pickUpEndTime","10:22:22");
order.put("pickUpReadyTime","12:12:12");
String requestBody = gson.toJson(order);
System.out.println("--request:");
System.out.println(requestBody);
String oPaySignature = hmacSHA512(requestBody, privateKey);
System.out.println("--signature:");
System.out.println(oPaySignature);
URL url = new URL(addr);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Authorization", "Bearer "+oPaySignature);
con.setRequestProperty("MerchantId", merchantId);
con.setDoOutput(true);
OutputStream os = con.getOutputStream();
byte[] input = requestBody.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), StandardCharsets.UTF_8));
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println("--response:");
System.out.println(response.toString());
//close your stream and connection
}
public static String hmacSHA512(final String data, final String secureKey) throws Exception{
byte[] bytesKey = secureKey.getBytes();
final SecretKeySpec secretKey = new SecretKeySpec(bytesKey, "HmacSHA512");
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(secretKey);
final byte[] macData = mac.doFinal(data.getBytes());
byte[] hex = new Hex().encode(macData);
return new String(hex, StandardCharsets.UTF_8);
}
}
Pickup Goods Response
-Response Parameters:
the parameters contained in the response received whenever you call the Pickup Goods payment API as a JSON Object.
{
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"payNo": "220321148180646777059",
"orderNo": "220321148180646777059",
"channelStatus": "PENDING",
"labelURL": "https://s3.amazonaws.com/rachna-prod/A3604E505DB24D118B9A2D48BDC336B3/Docket/R2SLUAT_INTERNAL_2022_30360/RSLUAT9399.pdf",
"packageStickerURL": "https://s3.amazonaws.com/rachna-prod/A3604E505DB24D118B9A2D48BDC336B3/Temp/RSLUAT9399.pdf",
"codStatus": "Data Received",
"trackingURL": "https://logixgrid.page.link/Uy4Yx",
"waybillNumber": "RSLUAT9399"
}
}
-Here is a detailed description for the parameters received in the response:
| Parameter | type | Description | example | |
|---|---|---|---|---|
| payNo | String |
payment No | 220321148180647368855 | |
| orderNo | String |
order number | 220321148180647368855 | |
| channelStatus | String |
Order status | PENDING | |
| labelURL | String |
Logistics order URL | https://s3.amazonaws.com/rachna-prod/A3604E505DB24D118B9A2D48BDC 336B3/Docket/R2SLUAT_INTERNAL_2022_30378/RSLUAT9408.pdf | |
| packageStickerURL | String |
Package sticker URL | https://s3.amazonaws.com/rachna-prod/A3604E505DB2 4D118B9A2D48BDC336B3/Temp/RSLUAT9408.pdf | |
| codStatus | String |
Logistics order status | DataReceived | |
| trackingURL | String |
Logistics status query URL | https://logixgrid.page.link/gMxAB | |
| waybillNumber | String |
Logistics order No | RSLUAT9408 | |
| failureCode | String |
fail error code. | payment fail error code, not blank when status [FAIL/CLOSE] | |
| failureReason | String |
fail error message. | payment fail error message, not blank when status [FAIL/CLOSE] | |
3.Order Query
In case you are still in development phase, you can call cashier payment status API using POST at the following staging endpoint API point URL
https://sandboxapi.opaycheckout.com/api/v1/international/cashier/status
Once you are ready for production, you should use the following production API endpoint URL instead
https://api.opaycheckout.com/api/v1/international/cashier/status
- Header: Authorization(API Calls Signature), MerchantId
- Json object containing the transaction information:
Authorization : Bearer {signature}
MerchantId : 256612345678901
{
"country": "EG",
"orderNo": "220321148180646777059"
}
HTTP POST Parameters
Detailed description of the parameters that you need to incorporate into your POST request are given in the table below.
An example call of COD payment status request is given below.
class OrderQueryController
{
private $secretkey;
private $merchantId;
private $url;
public function __construct() {
$this->merchantId = '281821120675251';
$this->secretkey = 'OPAYPRV16387******157474';
$this->url = 'https://sandboxapi.opaycheckout.com/api/v1/international/cashier/status';
}
public function test(){
$data = [
'country'=> 'EG',
'orderNo'=> '220321148180647543924'
]
;
$data2 = (string) json_encode($data,JSON_UNESCAPED_SLASHES);
$auth = $this->auth($data2);
$header = ['Content-Type:application/json', 'Authorization:Bearer '. $auth, 'MerchantId:'.$this->merchantId];
$response = $this->http_post($this->url, $header, json_encode($data));
$result = $response?$response:null;
return $result;
}
private function http_post ($url, $header, $data) {
if (!function_exists('curl_init')) {
throw new Exception('php not found curl', 500);
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$response = curl_exec($ch);
$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error=curl_error($ch);
curl_close($ch);
if (200 != $httpStatusCode) {
print_r("invalid httpstatus:{$httpStatusCode} ,response:$response,detail_error:" . $error, $httpStatusCode);
}
return $response;
}
public function auth ( $data ) {
$secretKey = $this->secretkey;
$auth = hash_hmac('sha512', $data, $secretKey);
return $auth;
}
}
const request = require('request');
var sha512 = require('js-sha512');
const formData = {
"country": "EG",
"orderNo": "220321148180646777059"
}
;
var privateKey = "OPAYPRV16387******157474"
var hash = sha512.hmac.create(privateKey);
hash.update(JSON.stringify(formData));
hmacsignature = hash.hex();
console.log(hmacsignature)
request({
url: 'https://sandboxapi.opaycheckout.com/api/v1/international/cashier/status',
method: 'POST',
headers: {
'MerchantId': '281821120675251',
'Authorization': 'Bearer '+hmacsignature
},
json: true,
body: formData
}, function (error, response, body) {
console.log('body: ')
console.log(body)
}
)
curl --location --request POST 'https://sandboxapi.opaycheckout.com/api/v1/international/cashier/status' \
--header 'MerchantId: 281821120675251' \
--header 'Authorization: Bearer dc716fff2092d5339fb7850d8b94c22d0a2ce3b343a4ad7c7643d614e91a255c2816e5466e9d2c4124e76e1cf8596f9e8f16520c35ec4cb31fcdf185b20d4822' \
--header 'Content-Type: application/json' \
--data-raw '{
"country": "EG",
"orderNo": "220321148180646907439"
}'
import com.google.gson.Gson;
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.TreeMap;
public class OrderQuery {
private static final String privateKey = "OPAYPRV16387******157474";
private static final String endpoint = "https://sandboxapi.opaycheckout.com";
private static final String merchantId = "281821120675251";
public static void main(String[] args) throws Exception {
String addr = endpoint + "/api/v1/international/cashier/status";
Gson gson = new Gson();
TreeMap order = new TreeMap<>();
order.put("country","EG");
order.put("orderNo","220321148180646953669");
String requestBody = gson.toJson(order);
System.out.println("--request:");
System.out.println(requestBody);
String oPaySignature = hmacSHA512(requestBody, privateKey);
System.out.println("--signature:");
System.out.println(oPaySignature);
URL url = new URL(addr);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Authorization", "Bearer "+oPaySignature);
con.setRequestProperty("MerchantId", merchantId);
con.setDoOutput(true);
OutputStream os = con.getOutputStream();
byte[] input = requestBody.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), StandardCharsets.UTF_8));
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println("--response:");
System.out.println(response.toString());
//close your stream and connection
}
public static String hmacSHA512(final String data, final String secureKey) throws Exception{
byte[] bytesKey = secureKey.getBytes();
final SecretKeySpec secretKey = new SecretKeySpec(bytesKey, "HmacSHA512");
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(secretKey);
final byte[] macData = mac.doFinal(data.getBytes());
byte[] hex = new Hex().encode(macData);
return new String(hex, StandardCharsets.UTF_8);
}
}
Order Query Response
-Response Parameters:
the parameters contained in the response received whenever you call the payment API as a JSON Object.
{
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"reference": "1647833340875",
"orderNo": "220321148180646777059",
"status": "PENDING",
"vat": {
"total": 0,
"currency": "EGP"
},
"amount": {
"total": 40000,
"currency": "EGP"
},
"createTime": 1647833341000,
"shippingTrackingInfo": {
"payNo": "220321148180646777059",
"waybillNumber": "RSLUAT9399",
"waybillJson": "[{\"logisticsStatus\":\"Data Received\",\"logisticsTime\":\"2022-03-21 03:30:47\",\"remark\":\"\",\"waybillNo\":\"RSLUAT9399\"}]"
}
}
}
-Here is a detailed description for the parameters received in the response:
| Parameter | type | Description | example | |
|---|---|---|---|---|
| reference | String |
Unique Merchant's payment order number. | 1001000 | |
| orderNo | String |
Unique Opay's payment order number. | 211009140896593010 | |
| createTime | String |
payment created timestamp. | 1633788085000 | |
| status | enum |
[INITIAL, PENDING, SUCCESS, FAIL, CLOSE] | SUCCESS |
|
| amount | ||||
| total | Integer |
amount(cent unit). | 400 | |
| currency | String |
currency type.See full list here | EGP | |
| vat | ||||
| total | Integer |
amount(cent unit). | 10 | |
| currency | String |
currency type.See full list here | EGP | |
| shippingTrackingInfo | ||||
| payNo | String |
logistics information pay number | 220321148180646777059 | |
| waybillNumber | String |
logistics information waybill number | RSLUAT9399 | |
| waybillJson | String |
logistics information details | [{\"logisticsStatus\":\"Data Received\" ,\"logisticsTime\":\"2022-03-21 03:30:47\",\"remark\" :\"\",\"waybillNo\":\"RSLUAT9399\"}] | |
| failureCode | String |
fail error code. | payment fail error code, not blank when status [FAIL/CLOSE] | |
| failureReason | String |
fail error message. | payment fail error message, not blank when status [FAIL/CLOSE] | |
4.Create COD Refund Payment
You can refund a paid payment using this API.
For calling the API using the POST method you can use these endpoints URL:
-In case you are still in the developing phase, use the following staging API endpoint URL
https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/create
-Once you have a fully tested payment flow and you are ready for production, Use the following production API endpoint URL instead
https://api.opaycheckout.com/api/v1/international/payment/refund/create
-Request Parameters:
- Header: Authorization(API Calls Signature), MerchantId
- Json object containing the transaction information:
Authorization : Bearer {signature}
MerchantId : 256612345678901
{
"amount": {
"currency": "EGP",
"total": 40000
},
"callbackUrl": "https://your-call-back-url",
"country": "EG",
"originalReference": "1647832408368",
"reference": "211217144657504157141",
"shippingAddressRefund": {
"actualWeight": "3.2",
"consigneeAddress": "consigneeAddress Street",
"consigneeCity": "Abdeen",
"consigneeCountry": "EG",
"consigneeName": "consigneeName test",
"consigneePhone": "1234567890",
"consigneeState": "CAIRO",
"consignorAddress": "consignorAddress Street",
"consignorCity": "Abdeen",
"consignorCountry": "EG",
"consignorState": "CAIRO",
"numberOfPackages": 1,
"packageDetails": [
{
"chargedWeight": "3.1",
"height": "3.1",
"length": "3.1",
"packageCount": 1,
"selectedPackageTypeCode": "BOX",
"weight": "5.1",
"width": "6.1"
}
],
"pickUpDate": "2012-01-01",
"pickUpEndTime": "22:22:22",
"pickUpReadyTime": "12:12:12",
"productAmount": 5,
"weightUnitType": "KILOGRAM"
}
}
HTTP POST Parameters
-Here is a detailed description for the parameters you need to complete the POST request:
-An example call of COD payment refund create API is as follows :
class CreateRefundPaymentController
{
private $secretkey;
private $merchantId;
private $url;
public function __construct() {
$this->merchantId = '281821120675251';
$this->secretkey = 'OPAYPRV16387******157474';
$this->url = 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/create';
}
public function test(){
$data = [
'amount'=> [
'currency'=> 'EGP',
'total'=> 40000
],
'callbackUrl'=> 'https://your-call-back-url',
'country'=> 'EG',
'originalReference'=> '1647856982794',
'reference'=> '211217144657504157142',
'shippingAddressRefund'=> [
'actualWeight'=> '3.2',
'consigneeAddress'=> 'consigneeAddress Street',
'consigneeCity'=> 'Abdeen',
'consigneeCountry'=> 'EG',
'consigneeName'=> 'consigneeName test',
'consigneePhone'=> '1234567890',
'consigneeState'=> 'CAIRO',
'consignorAddress'=> 'consignorAddress Street',
'consignorCity'=> 'Abdeen',
'consignorCountry'=> 'EG',
'consignorState'=> 'CAIRO',
'numberOfPackages'=> 1,
'packageDetails'=> [
[
'chargedWeight'=> '3.1',
'height'=> '3.1',
'length'=> '3.1',
'packageCount'=> 1,
'selectedPackageTypeCode'=> 'BOX',
'weight'=> '5.1',
'width'=> '6.1'
]
],
'pickUpDate'=> '2012-01-01',
'pickUpEndTime'=> '22:22:22',
'pickUpReadyTime'=> '12:12:12',
'productAmount'=> 5,
'weightUnitType'=> 'KILOGRAM'
]
]
;
$data2 = (string) json_encode($data,JSON_UNESCAPED_SLASHES);
$auth = $this->auth($data2);
$header = ['Content-Type:application/json', 'Authorization:Bearer '. $auth, 'MerchantId:'.$this->merchantId];
$response = $this->http_post($this->url, $header, json_encode($data));
$result = $response?$response:null;
return $result;
}
private function http_post ($url, $header, $data) {
if (!function_exists('curl_init')) {
throw new Exception('php not found curl', 500);
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$response = curl_exec($ch);
$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error=curl_error($ch);
curl_close($ch);
if (200 != $httpStatusCode) {
print_r("invalid httpstatus:{$httpStatusCode} ,response:$response,detail_error:" . $error, $httpStatusCode);
}
return $response;
}
public function auth ( $data ) {
$secretKey = $this->secretkey;
$auth = hash_hmac('sha512', $data, $secretKey);
return $auth;
}
}
const request = require('request');
var sha512 = require('js-sha512');
const formData = {
"amount": {
"currency": "EGP",
"total": 40000
},
"callbackUrl": "https://your-call-back-url",
"country": "EG",
"originalReference": "1647856987316",
"reference": "211217144657504157146",
"shippingAddressRefund": {
"actualWeight": "3.2",
"consigneeAddress": "consigneeAddress Street",
"consigneeCity": "Abdeen",
"consigneeCountry": "EG",
"consigneeName": "consigneeName test",
"consigneePhone": "1234567890",
"consigneeState": "CAIRO",
"consignorAddress": "consignorAddress Street",
"consignorCity": "Abdeen",
"consignorCountry": "EG",
"consignorState": "CAIRO",
"numberOfPackages": 1,
"packageDetails": [
{
"chargedWeight": "3.1",
"height": "3.1",
"length": "3.1",
"packageCount": 1,
"selectedPackageTypeCode": "BOX",
"weight": "5.1",
"width": "6.1"
}
],
"pickUpDate": "2012-01-01",
"pickUpEndTime": "22:22:22",
"pickUpReadyTime": "12:12:12",
"productAmount": 5,
"weightUnitType": "KILOGRAM"
}
}
;
var privateKey = "OPAYPRV16387******157474"
var hash = sha512.hmac.create(privateKey);
hash.update(JSON.stringify(formData));
hmacsignature = hash.hex();
console.log(hmacsignature)
request({
url: 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/create',
method: 'POST',
headers: {
'MerchantId': '281821120675251',
'Authorization': 'Bearer '+hmacsignature
},
json: true,
body: formData
}, function (error, response, body) {
console.log('body: ')
console.log(body)
}
)
curl --location --request POST 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/create' \
--header 'MerchantId: 281821120675251' \
--header 'Authorization: Bearer 4afd26a3e39ba57ad403b8e1d27b892f33b2a8090ce3635652a60f68d8eadfaac33dd959b38734a9f6699d59551ab792fa1291b429abe0aac153a26b14a4deb1' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": {
"currency": "EGP",
"total": 40000
},
"callbackUrl": "https://your-call-back-url",
"country": "EG",
"originalReference": "1647856847780",
"reference": "211217144657504157143",
"shippingAddressRefund": {
"actualWeight": "3.2",
"consigneeAddress": "consigneeAddress Street",
"consigneeCity": "Abdeen",
"consigneeCountry": "EG",
"consigneeName": "consigneeName test",
"consigneePhone": "1234567890",
"consigneeState": "CAIRO",
"consignorAddress": "consignorAddress Street",
"consignorCity": "Abdeen",
"consignorCountry": "EG",
"consignorState": "CAIRO",
"numberOfPackages": 1,
"packageDetails": [{
"chargedWeight": "3.1",
"height": "3.1",
"length": "3.1",
"packageCount": 1,
"selectedPackageTypeCode": "BOX",
"weight": "5.1",
"width": "6.1"
}],
"pickUpDate": "2012-01-01",
"pickUpEndTime": "22:22:22",
"pickUpReadyTime": "12:12:12",
"productAmount": 5,
"weightUnitType": "KILOGRAM"
}
}'
import com.google.gson.Gson;
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.TreeMap;
import java.util.UUID;
public class CreateCODRefundPayment {
private static final String privateKey = "OPAYPRV16387******157474";
private static final String endpoint = "https://sandboxapi.opaycheckout.com";
private static final String merchantId = "281821120675251";
public static void main(String[] args) throws Exception {
String addr = endpoint + "/api/v1/international/payment/refund/create";
Gson gson = new Gson();
TreeMap order = new TreeMap<>();
TreeMap amount = new TreeMap<>();
amount.put("currency","EGP");
amount.put("total",new Integer(40000));
order.put("amount",amount);
order.put("callbackUrl","https://your-call-back-url.com");
order.put("country","EG");
order.put("originalReference","1647856970295");
order.put("reference", UUID.randomUUID().toString());
TreeMap shippingAddressRefund = new TreeMap<>();
shippingAddressRefund.put("actualWeight","3.2");
shippingAddressRefund.put("consigneeAddress","consigneeAddress Street");
shippingAddressRefund.put("consigneeCity","Abaseya");
shippingAddressRefund.put("consigneeCountry","EG");
shippingAddressRefund.put("consigneeName","consigneeName test");
shippingAddressRefund.put("consigneePhone","1234567890");
shippingAddressRefund.put("consigneeState","CAIRO");
shippingAddressRefund.put("consignorAddress","consignorAddress Street");
shippingAddressRefund.put("consignorCity","Abaseya");
shippingAddressRefund.put("consignorCountry","EG");
shippingAddressRefund.put("consignorState","CAIRO");
shippingAddressRefund.put("numberOfPackages",1);
TreeMap packageDetail = new TreeMap<>();
packageDetail.put("chargedWeight", "3.1");
packageDetail.put("height", "3.1");
packageDetail.put("length", "3.1");
packageDetail.put("packageCount", 1);
packageDetail.put("selectedPackageTypeCode", "BOX");
packageDetail.put("weight", "5.1");
packageDetail.put("width", "6.1");
ArrayList packageDetails = new ArrayList<>();
packageDetails.add(packageDetail);
shippingAddressRefund.put("packageDetails",packageDetails);
shippingAddressRefund.put("pickUpDate","2012-01-01");
shippingAddressRefund.put("pickUpEndTime","10:22:22");
shippingAddressRefund.put("pickUpReadyTime","12:12:12");
shippingAddressRefund.put("productAmount",7);
shippingAddressRefund.put("weightUnitType","KILOGRAM");
order.put("shippingAddressRefund",shippingAddressRefund);
String requestBody = gson.toJson(order);
System.out.println("--request:");
System.out.println(requestBody);
String oPaySignature = hmacSHA512(requestBody, privateKey);
System.out.println("--signature:");
System.out.println(oPaySignature);
URL url = new URL(addr);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Authorization", "Bearer "+oPaySignature);
con.setRequestProperty("MerchantId", merchantId);
con.setDoOutput(true);
OutputStream os = con.getOutputStream();
byte[] input = requestBody.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), StandardCharsets.UTF_8));
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println("--response:");
System.out.println(response.toString());
//close your stream and connection
}
public static String hmacSHA512(final String data, final String secureKey) throws Exception{
byte[] bytesKey = secureKey.getBytes();
final SecretKeySpec secretKey = new SecretKeySpec(bytesKey, "HmacSHA512");
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(secretKey);
final byte[] macData = mac.doFinal(data.getBytes());
byte[] hex = new Hex().encode(macData);
return new String(hex, StandardCharsets.UTF_8);
}
}
Create COD Refund Payment Response
-Response Parameters:
the parameters contained in the response received whenever you call the Transaction Create API as a JSON Object.
{
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"orderNo": "220318258180646045954",
"merchantId": "281821120675251",
"country": "EG",
"reference": "211217144657504157141",
"orderStatus": "PENDING",
"refundAmount": {
"total": 40000,
"currency": "EGP"
},
"originalOrderNo": "220318148180646036529",
"codPickUpResponse": {
"payNo": "220318148180646036529",
"orderNo": "220318258180646045954",
"channelStatus": "PENDING",
"labelURL": "https://s3.amazonaws.com/rachna-prod/A3604E505DB24D118B9A2D48BDC336B3/Docket/R2SLUAT_INTERNAL_2022_30340/RSLUAT9394.pdf",
"packageStickerURL": "https://s3.amazonaws.com/rachna-prod/A3604E505DB24D118B9A2D48BDC336B3/Temp/RSLUAT9394.pdf",
"codStatus": "Data Received",
"trackingURL": "https://logixgrid.page.link/RnRhN",
"waybillNumber": "RSLUAT9394"
}
}
}
-Here is a detailed description for the parameters received in the response:
| Parameter | type | Description | example | |
|---|---|---|---|---|
| reference | String |
Merchant's refund order number. | 03948512001 | |
| orderNo | String |
OPay refund order number. | 211003140885499643 | |
| merchantId | String |
Merchant ID in OPay system. | 256612345678901 | |
| originalOrderNo | String |
OPay original order number. | 10212100000034000 | |
| refundAmount | ||||
| total | Integer |
amount(cent unit). | 400 | |
| currency | String |
currency type.See full list here | EGP | |
| country | String |
Country Code.See full list here | EG | |
| orderStatus | enum |
[INITIAL, PENDING, SUCCESS, FAIL] | SUCCESS |
|
| codPickUpResponse | ||||
| payNo | String |
payment No | 220321148180647368855 | |
| orderNo | String |
order number | 220321148180647368855 | |
| channelStatus | String |
Order status | PENDING | |
| labelURL | String |
Logistics order URL | https://s3.amazonaws.com/rachna-prod/A3604E505 DB24D118B9A2D48BDC 336B3/Docket/R2SLUAT_INTERN AL_2022_30378/RSLUAT9408.pdf | |
| packageStickerURL | String |
Package sticker URL | https://s3.amazonaws.com/rachna-prod/A3604E50 5DB24D118B9A2D48BDC336B3/Temp/RSLUAT9408.pdf | |
| codStatus | String |
Logistics order status | DataReceived | |
| trackingURL | String |
Logistics status query URL | https://logixgrid.page.link/gMxAB | |
| waybillNumber | String |
Logistics order No | RSLUAT9408 | |
5.Refund Order Query
you can get the status of a requested refund by using the Query Refund Status API.
For calling the API using the POST method you can use these endpoints URL:
-In case you are still in the developing phase, use the following staging API endpoint URL
https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/query
-Once you have a fully tested payment flow and you are ready for production, Use the following production API endpoint URL instead
https://api.opaycheckout.com/api/v1/international/payment/refund/query
-Request Parameters:
- Header: Authorization(API Calls Signature), MerchantId
- Json object containing the transaction information:
Authorization : Bearer {signature}
MerchantId : 256612345678901
{
"country": "EG",
"orderNo": "220318258180646045954"
}
HTTP POST Parameters
-Here is a detailed description for the parameters you need to complete the POST request:
-An example call of COD Query Refund Status API is as follows :
class RefundOrderQueryController
{
private $secretkey;
private $merchantId;
private $url;
public function __construct() {
$this->merchantId = '281821120675251';
$this->secretkey = 'OPAYPRV16387******157474';
$this->url = 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/query';
}
public function test(){
$data = [
'country'=> 'EG',
'orderNo'=> '220318258180646045954'
]
;
$data2 = (string) json_encode($data,JSON_UNESCAPED_SLASHES);
$auth = $this->auth($data2);
$header = ['Content-Type:application/json', 'Authorization:Bearer '. $auth, 'MerchantId:'.$this->merchantId];
$response = $this->http_post($this->url, $header, json_encode($data));
$result = $response?$response:null;
return $result;
}
private function http_post ($url, $header, $data) {
if (!function_exists('curl_init')) {
throw new Exception('php not found curl', 500);
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$response = curl_exec($ch);
$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error=curl_error($ch);
curl_close($ch);
if (200 != $httpStatusCode) {
print_r("invalid httpstatus:{$httpStatusCode} ,response:$response,detail_error:" . $error, $httpStatusCode);
}
return $response;
}
public function auth ( $data ) {
$secretKey = $this->secretkey;
$auth = hash_hmac('sha512', $data, $secretKey);
return $auth;
}
}
const request = require('request');
var sha512 = require('js-sha512');
const formData = {
"country": "EG",
"orderNo": "220318258180646045954"
}
;
var privateKey = "OPAYPRV16387******157474"
var hash = sha512.hmac.create(privateKey);
hash.update(JSON.stringify(formData));
hmacsignature = hash.hex();
console.log(hmacsignature)
request({
url: 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/query',
method: 'POST',
headers: {
'MerchantId': '281821120675251',
'Authorization': 'Bearer '+hmacsignature
},
json: true,
body: formData
}, function (error, response, body) {
console.log('body: ')
console.log(body)
}
)
curl --location --request POST 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/query' \
--header 'MerchantId: 281821120675251' \
--header 'Authorization: Bearer 7466e53bff0924fdce7c08c2ae290fcd66f8437b9fe2591ea95eb34f1993848f67cf4dcee1ca9c15dfa04d653482e6545e888c3314598c38a78e0076ca384d4d' \
--header 'Content-Type: application/json' \
--data-raw '{
"country": "EG",
"orderNo": "220318258180646045954"
}'
import com.google.gson.Gson;
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.TreeMap;
public class RefundOrderQuery {
private static final String privateKey = "OPAYPRV16387******157474";
private static final String endpoint = "https://sandboxapi.opaycheckout.com";
private static final String merchantId = "281821120675251";
public static void main(String[] args) throws Exception {
String addr = endpoint + "/api/v1/international/payment/refund/query";
Gson gson = new Gson();
TreeMap order = new TreeMap<>();
order.put("country","EG");
order.put("orderNo","220318258180646045954");
String requestBody = gson.toJson(order);
System.out.println("--request:");
System.out.println(requestBody);
String oPaySignature = hmacSHA512(requestBody, privateKey);
System.out.println("--signature:");
System.out.println(oPaySignature);
URL url = new URL(addr);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Authorization", "Bearer "+oPaySignature);
con.setRequestProperty("MerchantId", merchantId);
con.setDoOutput(true);
OutputStream os = con.getOutputStream();
byte[] input = requestBody.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), StandardCharsets.UTF_8));
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println("--response:");
System.out.println(response.toString());
//close your stream and connection
}
public static String hmacSHA512(final String data, final String secureKey) throws Exception{
byte[] bytesKey = secureKey.getBytes();
final SecretKeySpec secretKey = new SecretKeySpec(bytesKey, "HmacSHA512");
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(secretKey);
final byte[] macData = mac.doFinal(data.getBytes());
byte[] hex = new Hex().encode(macData);
return new String(hex, StandardCharsets.UTF_8);
}
}
Refund Order Query Response
-Response Parameters:
the parameters contained in the response received whenever you call the Transaction Create API as a JSON Object.
{
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"reference": "211217144657504157141",
"merchantId": "281821120675251",
"country": "EG",
"orderNo": "220318258180646045954",
"amount": {
"total": 40000,
"currency": "EGP"
},
"orderStatus": "PENDING",
"originalOrderNo": "220318148180646036529",
"originalAmount": {
"total": 40000,
"currency": "EGP"
},
"errorCode": null,
"errorMsg": null,
"createTime": 1647598594000,
"shippingTrackingInfo": {
"payNo": "220318258180646045954",
"waybillNumber": "RSLUAT9394",
"waybillJson": "[{\"logisticsStatus\":\"Data Received\",\"logisticsTime\":\"2022-03-18 10:16:51\",\"remark\":\"\",\"waybillNo\":\"RSLUAT9394\"}]"
}
}
}
-Here is a detailed description for the parameters received in the response:
| Parameter | type | Description | example | |
|---|---|---|---|---|
| reference | String |
Merchant's refund order number. | 03948512001 | |
| merchantId | String |
Merchant ID in OPay system. | 256612345678901 | |
| country | String |
Country Code.See full list here | EG | |
| orderNo | String |
OPay refund order number. | 211003140885499643 | |
| amount | ||||
| total | Integer |
amount(cent unit). | 400 | |
| currency | String |
Currency type.See full list here | EGP | |
| orderStatus | enum |
[INITIAL, PENDING, SUCCESS, FAIL] | SUCCESS |
|
| originalOrderNo | String |
OPay original order number. | 10212100000034000 | |
| originalAmount | ||||
| total | Integer |
amount(cent unit). | 400 | |
| currency | String |
Currency type.See full list here | EGP | |
| errorCode | String |
errorCode. | 02000 | |
| errorMsg | String |
errorMsg. | authentication failed. | |
| createTime | String |
payment created timestamp. | 1633788085000 | |
| shippingTrackingInfo | ||||
| payNo | String |
logistics information pay number | 220321148180646777059 | |
| waybillNumber | String |
logistics information waybill number | RSLUAT9399 | |
| waybillJson | String |
logistics information details | [{\"logisticsStatus\":\"Data Received\" ,\"logisticsTime\":\"2022-03-21 03:30:47\",\"remark\" :\"\",\"waybillNo\":\"RSLUAT9399\"}] | |
Error Handling
After submitting an API call to OPay, you receive a response back to inform you that
your request was received and processed. A successful OPay API should return a status code 00,
meanwhile, in a situation where any payment processing error occurred, you will receive an error code with a
message to describe the reason of the error. A sample error response can be found below.
{
"code": "02004",
"message": "the payment reference already exists."
}
Depending on the HTTP status code of the response, you should build some logic to handle any errors that a request or the system may return. A list of possible potential error codes that you may receive can be found below. A full list of all possible error codes can be found in the Error Codes section.
| Error Code | Error Message |
|---|---|
| 02000 | authentication failed. |
| 02001 | request parameters not valid. |
| 02003 | payMethod not support. |
| 02004 | the payment reference already exists. |
| 02002 | merchant not configured with this function. |
| 05057 | The agreementId does not exist |
| 05058 | The agreementId already exists |
| 05059 | The agreementId is invalid! |
| 05060 | The agreement has expired |
| 05061 | The agreement status is unavailable |
| 02007 | merchant not available. |
| 50003 | service not available, please try again. |
| 5023 | The %s parameter is required |
| 5024 | The value of enable3DS must be true |
What's Next?
Learn how to set up Payment Notifications Callback.
