Cancel Unpaid Order API
If your payment status is still unpaid, you can cancel your payment.
Depending on the status of your payment, FawryPay allows you to cancel payment that has been submitted by your customer. As long as the status of your payment is still unpaid, you can easily cancel the payment this API. A notification will be sent to customer via his/her mobile number if it exists with the payment information. Meanwhile, if the payment is already paid, you will need to use our Refund API to refund your customer.
Cancel Unpaid Order 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 |
|---|---|---|---|
| merchantAccount | String |
required | The merchant code provided during account setup. |
| orderRefNo | String |
required | The customer order reference number. |
| lang | String |
required | Language: "ar-eg" - "en-gb". This key will control the language of the notification message to the customer |
| signature | String |
required | The SHA-256 digested for the following concatenated string (orderRefNo + merchantAccount + lang + secureKey |
Sample API Calls
An example call of Cancel Unpaid Order API is given below.
function FawryPayCancelPayment(transaction_data) {
const PaymentData = {
merchantAccount: transaction_data.merchantCode,
orderRefNo: transaction_data.orderRefNo,
lang : transaction_data.lang,
signature : transaction_data.signature
};
// Use fetch to send request data to FawryPay cancel API.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/ECommerceWeb/api/orders/cancel-unpaid-order', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(PaymentData),
});
// Return and display the result of the charge.
return response.json();
}
$merchantAccount = '1tSa6uxz2nTwlaAmt38enA==';
$orderRefNo = 'O23890167';
$lang = 'en-gb';
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantAccount . $orderRefNo . $lang . $merchant_sec_key);
$httpClient = new \GuzzleHttp\Client(); // guzzle 6.3
$response = $httpClient->request('POST', 'https://atfawry.fawrystaging.com/ECommerceWeb/api/orders/cancel-unpaid-order', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json'
],
'body' => json_encode( [
'merchantAccount' => $merchantAccount,
'orderRefNo' => $orderRefNo,
'lang' => $lang,
'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 cancel API Endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/api/orders/cancel-unpaid-order"
# Payment Data
merchantAccount = '1tSa6uxz2nTwlaAmt38enA=='
orderRefNo = 'O23890167'
lang = 'en-gb'
merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef' // For the sake of demonstration
signature = hashlib.sha256(merchantAccount + orderRefNo + lang + merchant_sec_key).hexdigest()
# defining a params dict for the parameters to be sent to the API
PaymentData = {
'merchantAccount' : merchantAccount,
'orderRefNo' : orderRefNo,
'lang' : lang,
'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 FawryPayCancelPayment() {
let merchantAccount = '1tSa6uxz2nTwlaAmt38enA==';
let orderRefNo = 'O23890167';
let lang = 'en-gb';
let merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
let signature_body = orderRefNo.concat(merchantAccount, lang , 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/api/orders/cancel-unpaid-order', {
'merchantAccount' : merchantAccount,
'orderRefNo' : orderRefNo,
'lang' : lang,
'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/api/orders/cancel-unpaid-order \
-H "content-type: application/json" \
-X POST \
-d "{
"merchantAccount" : "1tSa6uxz2nTwlaAmt38enA==",
"orderRefNo" : "O23890167",
"lang" : "en-gb",
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/ECommerceWeb/api/orders/cancel-unpaid-order");
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 = "{
"merchantAccount": "1tSa6uxz2nTwlaAmt38enA==",
"orderRefNo": "O23890167",
"lang" : "en-gb",
"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/api/orders/cancel-unpaid-order", new fawrypay_request
{
merchantAccount = "1tSa6uxz2nTwlaAmt38enA==",
orderRefNo = "O23890167",
lang = "en-gb",
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 merchantAccount { get; set; }
public string orderRefNo { get; set; }
public string lang { 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:
{
"orderRefNo":"O23890167",
"merchantAccount":"1tSa6uxz2nTwlaAmt38enA==",
"lang": "en-gb",
"signature": "cf031d43901def1e209c1c74f2d6ef80da1e19331e1c94786f558dada612d118"
}
Response Parameters
FawryPay Sample Response
Whenever you call FawryPay cancel API, you may expect a response to inform you that your request was received. In case of successful cancelling process, you will receive a response code 200 with empty response body. Otherwise, you will receive a response in the form of JSON object which contains all cancel payment processing information.
Sample Payment cancel API Response
Response Parameters Description
| Parameter | type | Description | example |
|---|---|---|---|
| code | Integer |
The response status code | 9901, 9946, 9984 |
| description | String |
Exact description of the status of FawryPay response. | Operation done successfully Wrong Signature |
| reason | String |
Specific reason of the response. | BAD_REQUEST |
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. |
| 401 | Unauthorized. |
| 404 | Order not found. |
| 400 | Order already paid. |
| 400 | Order already cancelled. |
| 9901 | merchant code is blank or invalid. |
| 9938 | Order not found. |
| 9946 | Blank or invalid signature. |
| 9984 | Order is already canceled |
POSThttps://atfawry.fawrystaging.com/ECommerceWeb/api/orders/cancel-unpaid-orderResponse
// API Response Data Should Appear here
// This is a sample successful Response
{
"code": "9946",
"description": "Wrong Signature",
"reason": "BAD_REQUEST"
}
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.