myFawry App Payment
Introduction
The myFawry App payment method enables your customers to complete payments using the myFawry mobile application. When a customer initiates a payment through this method, your server receives two outputs in the API response: a deep link that opens the myFawry app directly (for mobile use cases) and a QR code the customer can scan with their camera (for web use cases). Your application presents whichever output matches the customer's device, the customer completes the payment inside the app, and your application verifies the transaction by polling the order status.
This method is ideal for merchants who want to provide a seamless, contactless, app-based payment experience across both mobile and web channels.
How It Works
After a customer clicks the payment button, your server should send a charge request to FawryPay with paymentMethod set to MYFAWRY . FawryPay will respond with two outputs: a deepLink (for mobile checkouts, which opens the myFawry app directly) and a qrCode URL (for web checkouts, which the customer scans with their mobile camera). Your application presents whichever output matches the customer's device. Once the payment is completed in the myFawry app, your application polls the Get Payment Status V2 API to verify the transaction.
1. Collect your client's payment details
Whenever your client is ready for checkout and selects myFawry as the preferred payment method, your application should submit the client's personal information (mobile number, email) along with the charge details to your server. Your server then constructs the charge request and submits it to FawryPay using the charge API described below.
A sampleJSON Object that can be passed from your payment form to your server is provided below.
2. Make myFawry Payment Request
Depending on the payment method selected by your client, you may proceed with myFawry Payment API.
myFawry Charge Request POST
TThis API is used to create a myFawry payment request. In case you are still in the 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 by FawryPay team during the account setup. | |
| merchantRefNum | Integer |
required | The unique reference number for the charge request in merchant system. | |
| customerProfileId | Integer |
optional | The unique customer profile ID in merchant system. This can be the user ID. | |
| paymentMethod | String |
required | Payment Method: MYFAWRY. | |
| customerName | String |
optional | The customer name in merchant system. | |
| customerMobile | String |
required | The customer mobile in merchant system: 01xxxxxxx | |
| customerEmail | String |
required | The customer e-mail in merchant system: test@email.com | |
| amount | Decimal |
required | The charge amount: must in the form of xx.xx | |
| paymentExpiry | Timestamp |
optional | Use this element to set specific expiration time for the generated order. After this time, the received reference number shall expire and the client will not be able to pay using it. This element take value as timestamp or in the format of date in milliseconds, e.g. 1631138400000. | |
| description | String |
required | Item description. | |
| orderWebHookUrl | URL String |
optional | WebHook Url used to notify your application back end when an event happens in this order like order paid , expired or refund for more details about the request message please check Server To Server Notification V2 | |
| language | String |
required | Language: "ar-eg" - "en-gb". This key will control the language of the notification message to the customer | |
| chargeItems
|
||||
| itemId | String |
required | The ID for the charge item | |
| description | String |
required | Description of charge item. | |
| price | Decimal |
required | Price per unit charge item. | |
| quantity | Decimal |
required | Quantity of the charge items. | |
| signature | String |
required | The SHA-256 digested for the following concatenated string "merchantCode + merchantRefNum + customerProfileId (if exist) + paymentMethod + amount (in two decimal format 10.00) + secureKey" | |
An example call of a myFawry payment with an amount of 580.55EGP is given below.
function FawryMYFAWRY(transaction_data) {
const PaymentData = {
merchantCode: transaction_data.merchantCode,
customerName: transaction_data.customerName,
customerMobile : transaction_data.customerMobile,
customerEmail : transaction_data.customerEmail,
customerProfileId : transaction_data.customerProfileId,
merchantRefNum : transaction_data.merchantRefNum,
amount : transaction_data.amount,
paymentExpiry : transaction_data.paymentExpiry,
currencyCode : transaction_data.currencyCode,
language: transaction_data.language, // "en-gb" or "ar-eg"
chargeItems : [
{
itemId : transaction_data.chargeItems.itemId,
description : transaction_data.chargeItems.description,
price : transaction_data.chargeItems.price,
quantity : transaction_data.chargeItems.quantity
}
],
signature : transaction_data.signature ,
paymentMethod : 'MYFAWRY' ,
description : 'transaction description'
};
// Use fetch to send the Payment Data to FawryPay.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(PaymentData),
});
// Return and display the result of the charge.
return response.json();
}
$merchantCode = '1tSa6uxz2nTwlaAmt38enA==';
$merchantRefNum = '23124654641';
$merchant_cust_prof_id = '777777';
$payment_method = 'MYFAWRY';
$amount = '580.55';
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $merchantRefNum . $merchant_cust_prof_id . $payment_method . $amount . $merchant_sec_key);
$httpClient = new \GuzzleHttp\Client(); // guzzle 6.3
$response = $httpClient->request('POST', 'https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json'
],
'body' => json_encode( [
'merchantCode' => $merchantCode,
'merchantRefNum' => $merchantRefNum,
'customerName' => 'Ahmed Ali',
'customerMobile' => '01234567891',
'customerEmail' => 'example@gmail.com',
'customerProfileId'=> '777777',
'amount' => '580.55',
'paymentExpiry' => 1631138400000,
'currencyCode' => 'EGP',
'language' => 'en-gb',
'chargeItems' => [
[
'itemId' => '897fa8e81be26df25db592e81c31c',
'description' => 'Item Description',
'price' => '580.55',
'quantity' => '1'
]
],
'signature' => $signature,
'paymentMethod' => $payment_method,
'description' => 'example description'
] , 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 MYFAWRY API Endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge"
# Payment Data
merchantCode = '1tSa6uxz2nTwlaAmt38enA=='
merchantRefNum = '23124654641'
merchant_cust_prof_id = '777777'
payment_method = 'MYFAWRY'
amount = '580.55'
merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef' // For the sake of demonstration
signature = hashlib.sha256(merchantCode + merchantRefNum + merchant_cust_prof_id + payment_method + amount + merchant_sec_key).hexdigest()
# defining a params dict for the parameters to be sent to the API
PaymentData = {
'merchantCode' : merchantCode,
'merchantRefNum' : merchantRefNum,
'customerName' : 'Ahmed Ali',
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'customerProfileId' : '777777',
'amount' : '580.55',
'paymentExpiry' : '1631138400000',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : {
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
},
'signature' : signature,
'paymentMethod' : payment_method,
'description': 'example description'
}
# sending post request and saving the response as response object
status_request = requests.post(url = URL, params = json.dumps(PaymentData))
# extracting data in json format
status_response = status_request.json()
// you Need to install sha256 and axios and import both inside js or by script tag
// sha256 from https://cdnjs.cloudflare.com/ajax/libs/js-sha256/0.9.0/sha256.min.js
//axios from https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js
import { sha256 } from 'js-sha256';
import axios from 'axios';
function FawryMYFAWRY() {
let merchantCode = "1tSa6uxz2nTwlaAmt38enA==";
let merchantRefNum = "23124654641";
let merchant_cust_prof_id = "777777";
let payment_method = "MYFAWRY";
let amount = "580.55";
let merchant_sec_key = "259af31fc2f74453b3a55739b21ae9ef";
let signature_body = merchantCode.concat(merchantCode , merchantRefNum , merchant_cust_prof_id , payment_method , amount , 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/charge', {
'merchantCode' : merchantCode,
'merchantRefNum' : merchantRefNum,
'customerName' : 'Ahmed Ali',
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'customerProfileId' : '777777',
'amount' : '580.55',
'paymentExpiry' : '1631138400000',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : [{
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
}],
'signature' : hash_signature,
'paymentMethod' : payment_method,
'description': 'example description'
})
.then(response => {
// Get Response Contents
let type = response.data.type;
let paymentStatus = response.data.paymentStatus;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge \
-H "content-type: application/json" \
-X POST \
-d "{
"merchantCode" : "1tSa6uxz2nTwlaAmt38enA==",
"merchantRefNum" : "23124654641",
"customerName" : "Ahmed Ali",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"customerProfileId" : "777777",
"amount" : 580.55,
"paymentExpiry" : "1631138400000",
"currencyCode" : "EGP",
"language" : "en-gb",
"chargeItems" : [{
"itemId" : "897fa8e81be26df25db592e81c31c",
"description" : "Item Description",
"price" : 580.55,
"quantity" : 1
}],
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"paymentMethod" : "MYFAWRY",
"description": "example description"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge");
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Accept", "application/json");
con.setDoOutput(true);
String jsonInputString = "{
"merchantCode" : "1tSa6uxz2nTwlaAmt38enA==",
"merchantRefNum" : "23124654641",
"customerName" : "Ahmed Ali",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"customerProfileId" : "777777",
"amount" : 580.55,
"paymentExpiry" : 1631138400000,
"currencyCode" : "EGP",
"language" : "en-gb",
"chargeItems" : [{
"itemId" : "897fa8e81be26df25db592e81c31c",
"description" : "Item Description",
"price" : 580.55,
"quantity" : 1
}],
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"paymentMethod" : "MYFAWRY",
"description": "example description"
}";
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/status", new fawrypay_request
{
merchantCode = "1tSa6uxz2nTwlaAmt38enA==",
merchantRefNum = "23124654641",
customerName = "Ahmed Ali",
customerMobile = "01234567891",
customerEmail = "example@gmail.com",
customerProfileId = "777777",
amount = 580.55,
paymentExpiry : 1631138400000,
currencyCode = "EGP",
language = "en-gb",
chargeItems = [{
itemId = "897fa8e81be26df25db592e81c31c",
description = "Item Description",
price = 580.55,
quantity = 1
}],
signature = "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
paymentMethod = "MYFAWRY",
description = "example description"
});
}
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 = "GET";
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 merchantRefNum { get; set; }
public string signature { get; set; }
public string merchantCode { get; set; }
public string merchantRefNum { get; set; }
public string customerName { get; set; }
public string customerMobile { get; set; }
public string customerEmail { get; set; }
public string customerProfileId { get; set; }
public string amount { get; set; }
public string paymentExpiry { get; set; }
public string currencyCode { get; set; }
public string language { get; set; }
public ChargeItems chargeItems;
public string signature { get; set; }
public string paymentMethod { get; set; }
public string description { get; set; }
}
public class ChargeItems
{
public string itemId { get; set; }
public string description { get; set; }
public string price { get; set; }
public string quantity { get; set; }
}
}
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:
Sample Request Data
{
"merchantCode": "1tSa6uxz2nTwlaAmt38enA==",
"customerName": "example",
"customerMobile": "01234567891",
"customerEmail": "example@gmail.com",
"customerProfileId": "777777",
"merchantRefNum": "2312465464",
"amount": "580.55",
"paymentExpiry" : "1631138400000",
"currencyCode": "EGP",
"language" : "en-gb",
"chargeItems": [
{
"itemId": "897fa8e81be26df25db592e81c31c",
"description": "Item Descriptoin",
"price": "580.55",
"quantity": "1"
}
],
"signature": "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36",
"paymentMethod": "MYFAWRY",
"description": "Example Description"
}
FawryPay Sample Response
Whenever you call FawryPay payment using myFawry Payment API, you may expect a response in the form of JSON object, The response returns two outputs to cover both customer device contexts:
Mobile Use Case — deepLink
When the customer is checking out on a mobile device, use the deepLink URL to open the myFawry app directly — no scanning needed.
Web Use Case — qrCode
When the customer is checking out on a desktop or web browser, render the qrCode image so they can scan it with their mobile camera.
Sample myFawry Payment API Response
Response Parameters Description
| Arguments | type | Description | example |
|---|---|---|---|
| type | String |
Type of response. | ChargeResponse |
| referenceNumber | String |
FawryPay issued transaction reference number. | 781434545 |
| merchantRefNumber | String |
Merchant issued transaction reference number. This is the same as the reference number you have set in your charge request. | 9c90d0f42040 |
| orderAmount | Decimal |
Order amount in two decimal places format. | 580.55 |
| paymentAmount | Decimal |
The paid amount in two decimal places format. | 580.55 |
| fawryFees | Decimal |
The payment processing fees. | 00.00 |
| paymentMethod | String |
Payment Method Selected by your client. | MYFAWRY |
| orderStatus | String |
Order Status. | UNPAID |
| deepLink | URL String |
A myFawry application deep link URL. Use this for the mobile use case — when the customer is checking out on a mobile device, render this as a tappable link or autoinvoke it to open the myFawry app directly and complete the payment. | https://www.myfawry.com/other/fawryPayData?btc=999&refNumber=781434545&btcType=POST&sourceAr=ShalooYC&sourceEn=ShalooYC&logo=https%3A%2F%2Fatfawry.fawrystaging.com%2Ffawrypay-api%2F770000021849%2Fmerchant-logo%2Fmerchant-logo.jpeg&merchantCode=770000021850 |
| qrCode | String |
The URL of the QR code image. Use this for the web use case — when the customer is checking out on a desktop or web browser, render this QR code on the checkout page so the customer can scan it with their mobile camera to open the myFawry app and complete the payment. | https://atfawry.fawrystaging.com/atfawry/myfawry/qr/9900357399 |
| paymentTime | Integer |
Timestamp to record when the payment has been processed. | 1607879720568 |
| customerProfileId | String |
Customer Profile ID in the merchant's system. | 1212 |
| signature | String |
Response Signature generated as the SHA-256 of the following concatenated string (referenceNumber (if exist) + merchantRefNum + paymentAmount (in two decimal places format 10.00) + orderAmount (in two decimal places format 10.00) + orderStatus + paymentMethod + fawryFees (if exist) (in two decimal places format 10.00)) + shippingFees (if exist) (in two decimal places format 10.00)) + authNumber (if exists) + customerMail (if exist) + customerMobile (if exist) + secureKey) | 2df2943c6704176809ba6d559e2906b3d4df14916d6 |
| statusCode | String |
Response status code. | 200 |
| statusDescription | String |
Response status description. | Operation done successfully |
Present the Payment Option to the Customer
After receiving the successful response from the myFawry charge API, your application should decide which output to present to the customer based on the device context. The API response provides both a deep link and a QR code to cover both use cases:
Mobile Use Case — Deep Link
When the customer is checking out from a mobile device (iOS or Android), use the deepLink value from the response. Render it as a tappable button or auto-invoke it to seamlessly open the myFawry application on the customer's device. This skips the scanning step entirely since the customer is already on their phone.
Web Use Case — QR Code
When the customer is checking out from a desktop or web browser on a non-mobile device, render the QR code image using the qrCode URL from the response. The customer scans the QR code with their mobile camera, which opens the myFawry application on their phone to complete the payment.
Check Payment Button
Regardless of which method the customer uses, your checkout page should include a Check Payment button that triggers a call to the Get Payment Status V2 API using the referenceNumber received in the charge response. The customer clicks this button after completing the payment in the myFawry app to verify the transaction.
myFawry Payment Status Response
Upon clicking the Check Payment button, your application should call the Get Payment Status V2 API to retrieve the current state of the order.
Sample Response:
Response Parameters Description
| Arguments | type | Description | example |
|---|---|---|---|
| orderStatus | String | The current status of the order in the FawryPay system. Possible values: UNPAID, PAID, EXPIRED, CANCELED, REFUNDED. | UNPAID |
| paymentTime | Timestamp | The exact timestamp indicating when the payment status was last updated, formatted as ISO 8601 (yyyy-MM-ddTHH:mm:ss.SSS). | 2026-04-22T10:59:14.207 |
Error Handling
After submitting an API call to FawryPay, you will receive a response to inform you that your request was received and processed. A list of possible error codes is below. For a full list, please check the Error Codes section.
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. |
| 9954 | Order is not paid |
Best Practices
- Ensure your checkout page clearly instructs the customer not to close the browser tab until the payment is verified.
- Display a loading indicator when the Check Payment button is clicked to provide feedback during the status check.
- Implement a retry mechanism allowing customers to click the Check Payment button multiple times if the status has not yet been updated.
- Use the Server Notification V2 webhook in parallel to receive real-time updates on the backend when the payment is confirmed.