OPay Refund Payment API
You can Refund a paid payment by using Refund Payment API.
OPay 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":400
},
"callbackUrl":"https://your-call-back-url.com",
"country":"EG",
"originalReference":"03948512",
"reference":"03948512001"
}
HTTP POST Parameters
-Here is a detailed description for the parameters you need to complete the POST request:
-An example call of payment refund API is as follows :
class PaymentRefundController
{
private $secretkey;
private $merchantId;
private $url;
public function __construct() {
$this->merchantId = '281821110129700';
$this->secretkey = 'OPAYPRV*******0187828';
$this->url = 'https://sandboxapi.opaycheckout.com/api/v1/international/payment/refund/create';
}
public function test(){
$data = [
'amount' => [
'currency' => 'EGP',
'total' => 400
],
'callbackUrl' => 'https://your-call-back-url.com',
'country' => 'EG',
'originalReference' => '0412339891033312',
'reference' => '04123398910033621'
]
;
$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;
}
}
# importing the requests library
import requests
# CashierAPI Endpoint
URL = "https://sandboxapi.opaycheckout.com/api/v1/international/transaction/refund "
# defining a params dict for the parameters to be sent to the API
PaymentData = {
'reference' : '1001000',
'originalReference' : '1001000',
'orderNo' : '10343543543532432',
}
# Prepare Headers
headers = {
'Content-Type' : 'application/json',
'Accept' : 'application/json',
'Authorization': '{signature}',
'MerchantId' : '256612345678901'
}
# sending post request and saving the response as response object
status_request = requests.post(url = URL, params = json.dumps(PaymentData), headers=headers)
# extracting data in json format
status_response = status_request.json()
const request = require('request');
var sha512 = require('js-sha512');
const formData ={
"amount":{
"currency":"EGP",
"total":400
},
"callbackUrl":"https://your-call-back-url.com",
"country":"EG",
"originalReference":"041233989101",
"reference":"04123398911111"
};
var privateKey = "OPAYPRV*******0187828"
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': '256621051120756',
'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: 256621051120756' \
--header 'Authorization: Bearer 38017496e*******2ab0297d1de8905cb7d85a043d9084254e61a8da6093b6f155550ff51891dca9f9889a' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount":{
"currency":"EGP",
"total":400
},
"callbackUrl":"https://your-call-back-url.com",
"country":"EG",
"originalReference":"04123398910027",
"reference":"0412339891003362"
}'
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;
import java.util.UUID;
public class PaymentRefund {
private static final String privateKey = "OPAYPRV*******0187828";
private static final String endpoint = "https://sandboxapi.opaycheckout.com";
private static final String merchantId = "256621051120756";
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(200));
order.put("amount",amount);
order.put("callbackUrl","https://your-call-back-url.com");
order.put("country","EG");
order.put("originalReference", "fb5ed330-edc1-4c2b-99e2-6b865cdf88f2");
order.put("reference", UUID.randomUUID().toString());
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);
}
}
using System;
using System.IO;
using System.Linq;
using System.Net;
using System.Text;
using Newtonsoft.Json;
namespace OPayRequest
{
public class Program
{
static void Main(string[] args)
{
PostJson("https://sandboxapi.opaycheckout.com/api/v1/international/transaction/refund ", new opay_request
{
reference = '12312321324',
originalReference = '1001000',
orderNo = '10343543543532432',
});
}
private static void PostJson(string uri, opay_request postParameters)
{
string postData = JsonConvert.SerializeObject(postParameters);
byte[] bytes = Encoding.UTF8.GetBytes(postData);
var httpWebRequest = (HttpWebRequest) WebRequest.Create(uri);
httpWebRequest.Method = "POST";
httpWebRequest.ContentLength = bytes.Length;
httpWebRequest.ContentType = "text/json";
using (Stream requestStream = httpWebRequest.GetRequestStream())
{
requestStream.Write(bytes, 0, bytes.Count());
}
var httpWebResponse = (HttpWebResponse) httpWebRequest.GetResponse();
if (httpWebResponse.StatusCode != HttpStatusCode.OK)
{
string message = String.Format("GET failed. Received HTTP {0}", httpWebResponse.StatusCode);
throw new ApplicationException(message);
}
}
}
public class opay_request
{
public string reference { get; set; }
public string orderNo { get; set; }
}
}
OPay 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": {
"reference": "03948512001",
"originalReference": "03948512",
"orderNo": "211003140885499643",
"originalOrderNo": "211003140885503763",
"country": "EG",
"refundAmount":{
"currency":"EGP",
"total":400
},
"orderStatus": "SUCCESS"
}
}
-Here is a detailed description for the parameters received in the response:
Parameter | type | Description | example | |
---|---|---|---|---|
reference | String |
Merchant's refund order number. | 03948512001 | |
originalReference | String |
Merchant's original order number. | 03948512 | |
orderNo | String |
OPay refund order number. | 211003140885499643 | |
originalOrderNo | String |
OPay original order number. | 10212100000034000 | |
refundAmount | ||||
total | Integer |
Refund 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 |
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": "02006",
"message": "original payment not found."
}
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 |
---|---|
09 | Time out. |
90 | System failure. |
91 | Refund error, please try again later. |
96 | Search order error, please try again later. |
97 | Create checkout session failed. |
98 | Invalid request header with requestId. |
99 | Request channel parameters are not valid. |
20000 | Duplicate merchant order number. |