Refund API
Issue a refund of a previous payment whenever needed.
FawryPay allows you to refund amounts that have previously been paid by customers, returning a unique reference for this request. Refunding can be done on the full captured amount or a partial amount. Payments which have been authorised, but not captured, cannot be refunded.
Refund API Endpoint
In case you are still in development phase, you will need to call our API using POST at the following staging endpoint API point URL
Meanwhile, whenever you are ready for production, you should use the following production API endpoint URL instead
Detailed description of the parameters that you need to incorporate into your POST request are given in the table below.
| Parameter | type | Required | Description |
|---|---|---|---|
| merchantCode | String |
required | The merchant code provided during account setup. |
| referenceNumber | String |
required | The customer order reference number. |
| refundAmount | Decimal |
required | The required amount to be refunded. |
| reason | String |
optional | The reason of the refund. |
| signature | String |
required | The SHA-256 digested for the following concatenated string merchantCode + referenceNumber + refund amount in two decimal format (10.00) + refund reason (if exists) + secureKey |
Sample API Calls
An example call of refund API for an amount of 362.50EGP is given below.
function FawryPayRefundPayment(transaction_data) {
const PaymentData = {
merchantCode: transaction_data.merchantCode,
referenceNumber: transaction_data.customerName,
refundAmount : transaction_data.customerMobile,
reason : transaction_data.customerEmail,
signature : transaction_data.signature
};
// Use fetch to send request data to FawryPay Refund API.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refund', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(PaymentData),
});
// Return and display the result of the charge.
return response.json();
}
$merchantCode = '1tSa6uxz2nTwlaAmt38enA==';
$referenceNumber = '23124654641';
$refundAmount = '362.50';
$reason = 'Item not as described';
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $referenceNumber . $refundAmount . $reason . $merchant_sec_key);
$httpClient = new \GuzzleHttp\Client(); // guzzle 6.3
$response = $httpClient->request('POST', 'https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refund', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json'
],
'body' => json_encode( [
'merchantCode' => $merchantCode,
'referenceNumber' => $referenceNumber,
'refundAmount' => $refundAmount,
'reason' => $reason,
'signature' => $signature
] , true)
]);
$response = json_decode($response->getBody()->getContents(), true);
$paymentStatus = $response['type']; // get response values
# importing the requests library
import requests
# importing Hash Library
import hashlib
# FawryPay Refund API Endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refund"
# Payment Data
merchantCode = '1tSa6uxz2nTwlaAmt38enA=='
referenceNumber = '23124654641'
refundAmount = '362.50'
reason = 'Item not as described'
merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef' // For the sake of demonstration
signature = hashlib.sha256(merchantCode + referenceNumber + refundAmount + reason + merchant_sec_key).hexdigest()
# defining a params dict for the parameters to be sent to the API
PaymentData = {
'merchantCode' : merchantCode,
'referenceNumber' : referenceNumber,
'refundAmount' : refundAmount,
'reason' : reason,
'signature' : signature
}
# sending get request and saving the response as response object
status_request = requests.get(url = URL, params = json.dumps(PaymentData))
# extracting data in json format
status_response = status_request.json()
function FawryPayRefundPayment() {
let merchantCode = '1tSa6uxz2nTwlaAmt38enA==';
let referenceNumber = '23124654641';
let refundAmount = '362.50';
let reason = 'Item not as described';
let merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
let signature_body = merchantCode.concat(referenceNumber , refundAmount , reason , merchant_sec_key);
let sha256 = new jsSHA('SHA-256', 'TEXT');
sha256.update(signature_body);
let hash_signature = sha256.getHash("HEX");
axios.post('https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refund', {
'merchantCode' : merchantCode,
'referenceNumber' : referenceNumber,
'refundAmount' : refundAmount,
'reason' : reason,
'signature' : hash_signature
})
.then(response => {
// Get Response Contents
let type = response.data.type;
let statusDescription = response.data.statusDescription;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refund \
-H "content-type: application/json" \
-X POST \
-d "{
"merchantCode" : "1tSa6uxz2nTwlaAmt38enA==",
"referenceNumber" : "23124654641",
"refundAmount" : "362.50",
"reason" : "Item not as described",
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refund");
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Accept", "application/json");
con.setDoOutput(true);
String jsonInputString = "{
"merchantCode": "1tSa6uxz2nTwlaAmt38enA==",
"referenceNumber": "23124654641",
"refundAmount" : "362.50",
"reason" : "Item not as described",
"signature": "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131"
}";
try(OutputStream os = con.getOutputStream()) {
byte[] input = jsonInputString.getBytes("utf-8");
os.write(input, 0, input.length);
}
try(BufferedReader br = new BufferedReader(
new InputStreamReader(con.getInputStream(), "utf-8"))) {
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println(response.toString());
}
using System;
using System.IO;
using System.Linq;
using System.Net;
using System.Text;
using Newtonsoft.Json;
namespace FawryPayRequest
{
public class Program
{
static void Main(string[] args)
{
PostJson("https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refund", new fawrypay_request
{
merchantCode = "1tSa6uxz2nTwlaAmt38enA==",
referenceNumber = "23124654641",
refundAmount = "362.50",
reason = "Item not as described",
signature = "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131"
});
}
private static void PostJson(string uri, fawrypay_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 fawrypay_request
{
public string merchantCode { get; set; }
public string referenceNumber { get; set; }
public string refundAmount { get; set; }
public string reason { get; set; }
public string signature { get; set; }
}
}
Request Parameters
Regardless of the choice of your preferred language, any of the code snippets above should produce an POST request containing the following JSON object in the request header:
{
"merchantCode" : "1tSa6uxz2nTwlaAmt38enA==",
"referenceNumber" : "23124654641",
"refundAmount" : "362.50",
"reason" : "Item not as described",
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131"
}
Response Parameters
FawryPay Sample Response
Whenever you call FawryPay Refund API, you may expect a response in the form of JSON object which contains all refund processing information.
Sample Payment Refund API Response
Response Parameters Description
| Parameter | type | Description | example |
|---|---|---|---|
| type | String |
Specific type of the response. | ChargeResponse |
| statusCode | Integer |
The response status code | 200 |
| statusDescription | String |
Exact description of the status of FawryPay response. | Operation done successfully Wrong Signature |
Error Handling
After submitting an API call to FawryPay, you receive a response back to inform you that your request was received and processed. A sample error response can be found below.
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 found below. For a full list of all possible error codes can be found in the Error Codes section.
| Error Code | Description |
|---|---|
| 200 | Operation done successfully. |
| 9901 | merchant code is blank or invalid. |
| 9938 | Order not found. |
| 9946 | Blank or invalid signature. |
| 9935 | Refunded amount greater than paid amount. |
| 9954 | Order is not paid |
POSThttps://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/refundResponse
// API Response Data Should Appear here
// This is a sample successful Response
{
"type": "ChargeResponse",
"statusCode": 200,
"statusDescription": "Operation done successfully"
}
Next steps
Extend your Integration
Was this page helpful?
Thank you for helping improve FawryPay's documentation. If you need help or have any questions, please consider contacting support.