Create Payments with Bank Installments
Learn how your clients can convert their purchases into monthly installments.
Throughout this page, you will be guided to obtain a fully functional server to server integration. You will also learn how to use our set of comprehensive APIs to create payments using cards or pay at FawryPay POS payment methods. You will also learn how to create cards' tokens for your clients for a more secure usage.
1. Get Installment Plans GET
This API can be used to retrieve your installments plans. In case you are still in development phase, you will need to call our API using GET 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
In order to retrieve the payments plans associated with your account, you will need to incorporate
your accountNumber into your GET request.
| Parameter | type | required | Description |
|---|---|---|---|
| accountNumber | String |
required | The merchant code provided by FawryPay team during the account setup. |
An example call of get installment plans API is given below.
function FawryGetInstallmentPlans(transaction_data) {
const PaymentData = {
accountNumber: transaction_data.accountNumber
};
// Use fetch to send the Get Installment Plans API.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plans', {
method: 'GET',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(PaymentData),
});
// Return and display the result of the charge.
return response.json();
}
$accountNumber = '1tSa6uxz2nTwlaAmt38enA==';
$httpClient = new \GuzzleHttp\Client(); // guzzle 6.3
$response = $httpClient->request('GET', 'https://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plans', [
'query' => [
'accountNumber' => $accountNumber
]
]);
$response = json_decode($response->getBody()->getContents(), true);
$installmentPlan = $response['installmentPlan']; // get response values
# importing the requests library
import requests
# Get Installment Plans API Endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plans"
# defining a params dict for the parameters to be sent to the API
RequestData = {
'accountNumber' : '1tSa6uxz2nTwlaAmt38enA=='
}
# sending post request and saving the response as response object
status_request = requests.get(url = URL, params = json.dumps(RequestData))
# extracting data in json format
status_response = status_request.json()
function FawryGetInstallmentPlans() {
let merchantCode = "1tSa6uxz2nTwlaAmt38enA==";
axios.get('https://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plans', {
'accountNumber' : merchantCode
})
.then(response => {
// Get Response Contents
let accountType = response.data.accountType;
let installmentPlan = response.data.installmentPlan;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plans \
-X GET \
-d accountNumber = 1tSa6uxz2nTwlaAmt38enA==
URL url = new URL ("https://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plans");
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 = "{
"accountNumber": "1tSa6uxz2nTwlaAmt38enA=="
}";
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/merchant/installment-plans", new fawrypay_request
{
accountNumber = "1tSa6uxz2nTwlaAmt38enA=="
});
}
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 accountNumber { get; set; }
}
}
Regardless of the choice of your preferred language, any of the code snippets above should produce an GET request as follows:
Sample Request Data
https://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plans?accountNumber=1tSa6uxz2nTwlaAmt38enA==
FawryPay Sample Response
Whenever you call get installment plans API, you may expect a response in the form of JSON object which contains your installment plans information.
{
"id":1,
"installmentPlan":{
"id":1,
"nameAr":"5 months",
"nameEn":"5 months",
"rate":5.0,
"noOfMonths":5,
"merchantProfileCode":"TEST525785",
"minAmount":10.0,
"maxAmount":1000.0,
"startDate":1555891200000,
"endDate":1598832000000,
"online":true,
"status":{
"id":1,
"code":"ACTIVE",
"nameAr":"ACTIVE",
"nameEn":"ACTIVE"
},
"accountType":{
"id":1,
"nameEn":"VC",
"nameAr":"VC",
"code":"VC",
"bank":{
"id":1,
"nameEn":"VC",
"nameAr":"VC",
"code":"VC",
"swfCode":"VC"
},
"pans":[
"500555",
"500555",
"600555",
"700555",
"800555",
"512345"
]
},
"type":"INDIRECT"
},
"applyTo":"ANY_PRODUCT",
"products":[
],
"productsCodes":[
],
"variants":[
],
"categories":[
],
"requiredItemsValidation":false
}
Response Parameters Description
| Parameter | type | Description | example | |||
|---|---|---|---|---|---|---|
| id | Integer |
|||||
| installmentPlan
|
||||||
| id | Integer |
Plan ID | 1 | |||
| nameAr | String |
Arabic name of the plan | 5 months | |||
| nameEn | String |
English name of the plan | 5 months | |||
| rate | Decimal |
The rate which the customer will pay if he selected this plan. It will be added to the original order amount. | 5.0 | |||
| noOfMonths | Integer |
Number of month of the plan | 5 | |||
| merchantProfileCode | String |
Profile code of the merchant | TEST525785 | |||
| minAmount | Decimal |
The order amount should be between the minimum and maximum in order to be able to go with this plan | 10.0 | |||
| maxAmount | Decimal |
10.0 | ||||
| startDate | Integer |
Effective start date and end date of this plan | 1555891200000 | |||
| endDate | Integer |
1598832000000 | ||||
| online | Boolean |
true | ||||
| status
|
||||||
| id | Integer |
The status code and we always return the active plans only back to the client | 1 | |||
| Code | String |
ACTIVE | ||||
| nameAr | String |
ACTIVE | ||||
| nameEn | String |
ACTIVE | ||||
| accountType
|
||||||
| id | Integer |
Represents the card name for example NBE credit card | 1 | |||
| nameAr | String |
ACTIVE | ||||
| nameEn | String |
ACTIVE | ||||
| Code | String |
ACTIVE | ||||
| bank
|
||||||
| id | Integer |
1 | ||||
| nameAr | String |
VC | ||||
| nameEn | String |
VC | ||||
| Code | String |
VC | ||||
| swfCode | String |
VC | ||||
| pans | List |
List of card pans. If the card matches one of them, then he can select this plan. | [ "500555", "600555", "700555"] | |||
| type | String |
INDIRECT | ||||
| applyTo | String |
ANY_PRODUCT | ||||
| products | Array |
If the plan configured for specific products, this list will contain the products SKUs. | ANY_PRODUCT | |||
| productsCodes | Array |
If the plan configured for specific variants, this list will contain the variants SKUs. | ANY_PRODUCT | |||
| variants | Array |
ANY_PRODUCT | ||||
| categories | Array |
If the plan configured for specific categories, this list will contain the categories codes. | ANY_PRODUCT | |||
| requiredItemsValidation | Array |
ANY_PRODUCT | ||||
GEThttps://atfawry.fawrystaging.com/ECommerceWeb/api/merchant/installment-plansResponse
// API Response Data Should Appear here
// This is a sample successful Response
{
"id":1,
"installmentPlan":{
"id":1,
"nameAr":"5 months",
"nameEn":"5 months",
"rate":5.0,
"noOfMonths":5,
"merchantProfileCode":"TEST525785",
"minAmount":10.0,
"maxAmount":1000.0,
"startDate":1555891200000,
"endDate":1598832000000,
"online":true,
"status":{
"id":1,
"code":"ACTIVE",
"nameAr":"ACTIVE",
"nameEn":"ACTIVE"
},
"accountType":{
"id":1,
"nameEn":"VC",
"nameAr":"VC",
"code":"VC",
"bank":{
"id":1,
"nameEn":"VC",
"nameAr":"VC",
"code":"VC",
"swfCode":"VC"
},
"pans":[
"500555",
"500555",
"600555",
"700555",
"800555",
"512345"
]
},
"type":"INDIRECT"
},
"applyTo":"ANY_PRODUCT",
"products":[
],
"productsCodes":[
],
"variants":[
],
"categories":[
],
"requiredItemsValidation":false
}
2. Collect your client's payment details
Whenever your client is ready for checkout, you will need to present your own payment details form. This form should collect all payment details, i.e. preferred payment method , card details, and client's personal information. After collecting the required information, pass them to your server so your application can decide on the right Payment API to proceed with. For example, if the user choose to pay with his card, then, Pay with Card API is the right one to go with.
A sampleJSON Object that can be passed from your payment form to your server is provided below.
3. Make Bank Installment Payment
Depending on the payment method selected by your client, you may proceed with one of our bank installment payment APIs. You can issue installment payments either using client's card or using a pre-saved card token.
Installment Charge Request using Card POST
This API can be used to charge the client installment using his card information. 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
HTTP POST Parameters
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: PAYATFAWRY, CASHONDELIVERY, CARD, MWALLET. | |
| cardNumber | Integer |
required | Card Number. | |
| cardExpiryYear | Integer |
required | Card Expiry Year in two digits format: 21, 22. | |
| cardExpiryMonth | Integer |
required | Card Expiry Month in two digits format: 05, 12. | |
| cvv | Integer |
required | Card cvv code. | |
| 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 be in the form of xx.xx. | |
| description | String |
required | Item description. | |
| 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. | |
| installmentPlanId | Integer |
required | Installment Plan ID | |
| signature | String |
required | The SHA-256 digested for the following concatenated string "merchantCode + merchantRefNum + customerProfileId + paymentMethod + amount (in two decimal format 10.00) + cardNumber + cardExpiryYear + cardExpiryMonth + cvv + installmentPlanId + secureKey" | |
An example call of installment charge using card with an amount of 580.55EGP is given below.
function FawryPayWithCard(transaction_data) {
const PaymentData = {
merchantCode: transaction_data.merchantCode,
customerName: transaction_data.customerName,
customerMobile : transaction_data.customerMobile,
customerEmail : transaction_data.customerEmail,
customerProfileId : transaction_data.customerProfileId,
cardNumber : transaction_data.cardNumber,
cardExpiryYear : transaction_data.cardExpiryYear,
cardExpiryMonth : transaction_data.cardExpiryMonth,
cvv : transaction_data.cvv,
merchantRefNumber : transaction_data.merchantRefNumber,
amount : transaction_data.amount,
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
}
],
installmentPlanId : transaction_data.installmentPlanId ,
signature : transaction_data.signature ,
paymentMethod : 'CARD' ,
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==';
$merchantRefNumber = '23124654641';
$merchant_cust_prof_id = '777777';
$payment_method = 'CARD';
$amount = '580.55';
$cardNumber = '4242424242424242',
$cardExpiryYear = '21';
$cardExpiryMonth = '05';
$cvv = 123;
$installmentPlanId = 1952;
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $merchantRefNumber . $merchant_cust_prof_id . $payment_method . $amount . $cardNumber .
$cardExpiryYear . $cardExpiryMonth . $cvv . $installmentPlanId . $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,
'merchantRefNumber' => $merchantRefNumber,
'customerName' => 'Ahmed Ali',
'customerMobile' => '01234567891',
'customerEmail' => 'example@gmail.com',
'customerProfileId'=> '777777',
'cardNumber' => '4242424242424242',
'cardExpiryYear' => '21',
'cardExpiryMonth' => '05',
'cvv' => '123',
'amount' => '580.55',
'currencyCode' => 'EGP',
'language' => 'en-gb',
'chargeItems' => [
'itemId' => '897fa8e81be26df25db592e81c31c',
'description' => 'Item Description',
'price' => '580.55',
'quantity' => '1'
],
'installmentPlanId' => $installmentPlanId,
'signature' => $signature,
'paymentMethod' => 'CARD',
'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
# FawryPayAPI Endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge"
# Payment Data
merchantCode = '1tSa6uxz2nTwlaAmt38enA=='
merchantRefNumber = '23124654641'
merchant_cust_prof_id = '777777'
payment_method = 'CARD'
amount = '580.55'
cardNumber = '4242424242424242'
cardExpiryYear = '21'
cardExpiryMonth = '05'
cvv = 123
installmentPlanId = 1952
merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef' // For the sake of demonstration
signature = hashlib.sha256(merchantCode + merchantRefNumber + merchant_cust_prof_id + payment_method +
amount + cardNumber + cardExpiryYear + cardExpiryMonth + cvv + installmentPlanId + merchant_sec_key).hexdigest()
# defining a params dict for the parameters to be sent to the API
PaymentData = {
'merchantCode' : merchantCode,
'merchantRefNumber' : merchantRefNumber,
'customerName' : 'Ahmed Ali',
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'customerProfileId' : '777777',
'cardNumber' : '4242424242424242',
'cardExpiryYear' : '21',
'cardExpiryMonth' : '05',
'cvv' : '123',
'amount' : '580.55',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : {
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
},
'installmentPlanId' : installmentPlanId,
'signature' : signature,
'paymentMethod' : 'CARD',
'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 FawryPayWithCard() {
let merchantCode = "1tSa6uxz2nTwlaAmt38enA==";
let merchantRefNumber = "23124654641";
let merchant_cust_prof_id = "777777";
let payment_method = "CARD";
let amount = "580.55";
let cardNumber = "4242424242424242";
let cardExpiryYear = "21";
let cardExpiryMonth = "05";
let cvv = 123;
let installmentPlanId = 1952;
let merchant_sec_key = "259af31fc2f74453b3a55739b21ae9ef";
let signature_body = merchantCode.concat(merchantCode , merchantRefNumber , merchant_cust_prof_id , payment_method ,
amount , cardNumber , cardExpiryYear , cardExpiryMonth , cvv , installmentPlanId, 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,
'merchantRefNumber' : merchantRefNumber,
'customerName' : 'Ahmed Ali',
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'customerProfileId' : '777777',
'cardNumber' : '4242424242424242',
'cardExpiryYear' : '21',
'cardExpiryMonth' : '05',
'cvv' : '123',
'amount' : '580.55',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : {
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
},
'installmentPlanId' : installmentPlanId,
'signature' : hash_signature,
'paymentMethod' : 'CARD',
'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==",
"merchantRefNumber" : "23124654641",
"customerName" : "Ahmed Ali",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"customerProfileId" : "777777",
"cardNumber" : "4242424242424242",
"cardExpiryYear" : "21",
"cardExpiryMonth" : "05",
"cvv" : 123,
"amount" : 580.55,
"currencyCode" : "EGP",
"language" : "en-gb",
"chargeItems" : {
"itemId" : "897fa8e81be26df25db592e81c31c",
"description" : "Item Description",
"price" : 580.55,
"quantity" : 1
},
"installmentPlanId" : 1952,
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"paymentMethod" : "CARD",
"description": "example description"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge");
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==",
"merchantRefNumber" : "23124654641",
"customerName" : "Ahmed Ali",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"customerProfileId" : "777777",
"cardNumber" : "4242424242424242",
"cardExpiryYear" : "21",
"cardExpiryMonth" : "05",
"cvv" : 123,
"amount" : 580.55,
"currencyCode" : "EGP",
"language" : "en-gb",
"chargeItems" : {
"itemId" : "897fa8e81be26df25db592e81c31c",
"description" : "Item Description",
"price" : 580.55,
"quantity" : 1
},
"installmentPlanId" : 1952,
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"paymentMethod" : "CARD",
"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/charge", new fawrypay_request
{
merchantCode = "1tSa6uxz2nTwlaAmt38enA==",
merchantRefNumber = "23124654641",
customerName = "Ahmed Ali",
customerMobile = "01234567891",
customerEmail = "example@gmail.com",
customerProfileId = "777777",
cardNumber = "4242424242424242",
cardExpiryYear = "21",
cardExpiryMonth = "05",
cvv = 123,
amount = 580.55,
currencyCode = "EGP",
language = "en-gb",
chargeItems = {
itemId = "897fa8e81be26df25db592e81c31c",
description = "Item Description",
price = 580.55,
quantity = 1
},
installmentPlanId = "1952",
signature = "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
payment_method = CARD,
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 = "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 merchantRefNumber { get; set; }
public string signature { get; set; }
public string merchantCode { get; set; }
public string merchantRefNumber { get; set; }
public string customerName { get; set; }
public string customerMobile { get; set; }
public string customerEmail { get; set; }
public string customerProfileId { get; set; }
public string cardNumber { get; set; }
public string cardExpiryYear { get; set; }
public string cardExpiryMonth { get; set; }
public string cvv { get; set; }
public string amount { get; set; }
public string currencyCode { get; set; }
public string language { get; set; }
public ChargeItems chargeItems;
public string installmentPlanId { get; set; }
public string signature { get; set; }
public string payment_method { 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; }
}
}
Sample Request Data
{
"merchantCode": "1tSa6uxz2nTwlaAmt38enA==",
"customerName": "example",
"customerMobile": "01234567891",
"customerEmail": "example@gmail.com",
"customerProfileId": "777777",
"cardNumber": "4242424242424242",
"cardExpiryYear": "25",
"cardExpiryMonth": "05",
"cvv": "123",
"merchantRefNum": "2312465464",
"amount": "580.55",
"currencyCode": "EGP",
"language" : "en-gb",
"chargeItems": [
{
"itemId": "897fa8e81be26df25db592e81c31c",
"description": "Item Descriptoin",
"price": "580.55",
"quantity": "1"
}
],
"installmentPlanId" : 1952,
"signature": "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36",
"paymentMethod": "CARD",
"description": "Example Description"
}
FawryPay Sample Response
Whenever you call FawryPay installment charge using card API, you may expect a response in the form of JSON object which contains all necessary payment processing information.
Sample Installment Payment using Card API Response
Response Parameters Description
| Arguments | type | Description | example |
|---|---|---|---|
| type | String |
Type of response. | ChargeResponse |
| referenceNumber | String |
FawryPay issued transaction reference number. | 963455678 |
| merchantRefNumber | String |
Merchant issued transaction reference number. This is the same as the reference number you have set in your charge request. | 9990d0642040 |
| orderAmount | Decimal |
Order amount in two decimal places format. | 20.00 |
| paymentAmount | Decimal |
The paid amount in two decimal places format. | 20.00 |
| fawryFees | Decimal |
The payment processing fees. | 1.00 |
| paymentMethod | String |
Payment Method Selected by your client. | 'CashOnDelivery', 'PayAtFawry', 'MWALLET', 'CARD' or 'VALU' |
| orderStatus | String |
Order Status. | PAID |
| paymentTime | Integer |
Timestamp to record when the payment has been processed. | 1607879720568 |
| customerMobile | String |
Customer Mobile Number. | 01234567891 |
| customerMail | String |
Customer E-mail address. | example@email.com |
| authNumber | String |
Payment authentication number | 12336534 |
| 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 |
POSThttps://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/chargeResponse
// API Response Data Should Appear here
// This is a sample successful Response
{
"type": "ChargeResponse",
"referenceNumber": "963455678",
"merchantRefNumber": "9990d0642040",
"orderAmount": 20.00,
"paymentAmount": 20.00,
"fawryFees": 1.00,
"paymentMethod": "CARD",
"orderStatus": "PAID",
"paymentTime": 1607879720568,
"customerMobile": "01234567891",
"customerMail": "example@gmail.com",
"authNumber": "12336534",
"customerProfileId": "1212",
"signature": "b0ef178e2f06b215b18cfc7d82fb5d1f7b95dfcc91e33f8a6ce1e1251fdd04ec",
"statusCode": 200,
"statusDescription": "Operation done successfully"
}
Installment Charge Request using Card TokenPOST
This API can be used to charge the client installment using his pre-saved card Token information. 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
HTTP POST Parameters
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: CARD. | |
| cardToken | String |
required | Pre-saved client's card token. | |
| cvv | Integer |
required | Card cvv code. | |
| 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 be in the form of xx.xx. | |
| description | String |
required | Item description. | |
| 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. | |
| installmentPlanId | Integer |
required | Installment Plan ID | |
| signature | String |
required | The SHA-256 digested for the following concatenated string "merchantCode + merchantRefNum + customerProfileId + paymentMethod + amount (in two decimal format 10.00) + cardToken + cvv + installmentPlanId + secureKey" | |
An example call of installment charge using card token with an amount of 580.55EGP is given below.
function FawryPayWithCardToken(transaction_data) {
const PaymentData = {
merchantCode: transaction_data.merchantCode,
customerMobile : transaction_data.customerMobile,
customerEmail : transaction_data.customerEmail,
customerProfileId : transaction_data.customerProfileId,
cardToken : transaction_data.cardToken,
cvv : transaction_data.cvv,
merchantRefNumber : transaction_data.merchantRefNumber,
amount : transaction_data.amount,
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
}
],
installmentPlanId : transaction_data.installmentPlanId ,
signature : transaction_data.signature ,
paymentMethod : 'CARD' ,
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==';
$merchantRefNumber = '23124654641';
$merchant_cust_prof_id = '777777';
$payment_method = 'CARD';
$amount = '580.55';
$card_token = 'ac0a1909256e8bb5a35a6311c5e824c223d13ae877c5bb0419350b01c619d59d';
$cvv = 123;
$installmentPlanId = 1952;
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $merchantRefNumber . $merchant_cust_prof_id . $payment_method . $amount . $card_token . $cvv . $installmentPlanId . $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,
'merchantRefNumber' => $merchantRefNumber,
'customerMobile' => '01234567891',
'customerEmail' => 'example@gmail.com',
'customerProfileId'=> '777777',
'cardToken' => '4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1',
'cvv' => '123',
'amount' => '580.55',
'currencyCode' => 'EGP',
'language' => 'en-gb',
'chargeItems' => [
'itemId' => '897fa8e81be26df25db592e81c31c',
'description' => 'Item Description',
'price' => '580.55',
'quantity' => '1'
],
'installmentPlanId' => $installmentPlanId,
'signature' => $signature,
'paymentMethod' => 'CARD',
'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 Installment Charge using Card Token API Endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge"
# Payment Data
merchantCode = '1tSa6uxz2nTwlaAmt38enA=='
merchantRefNumber = '23124654641'
merchant_cust_prof_id = '777777'
payment_method = 'CARD'
amount = '580.55'
cvv = 123
card_token = 'ac0a1909256e8bb5a35a6311c5e824c223d13ae877c5bb0419350b01c619d59d'
installmentPlanId = 1952
merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef' // For the sake of demonstration
signature = hashlib.sha256(merchantCode + merchantRefNumber + merchant_cust_prof_id + payment_method + amount + card_token + cvv + installmentPlanId + merchant_sec_key).hexdigest()
# defining a params dict for the parameters to be sent to the API
PaymentData = {
'merchantCode' : merchantCode,
'merchantRefNumber' : merchantRefNumber,
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'customerProfileId' : '777777',
'cardToken' : '4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1',
'cvv' : '123',
'amount' : '580.55',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : {
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
},
'installmentPlanId' : installmentPlanId,
'signature' : signature,
'paymentMethod' : 'CARD',
'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()
function FawryPayWithCardToken() {
let merchantCode = "1tSa6uxz2nTwlaAmt38enA==";
let merchantRefNumber = "23124654641";
let merchant_cust_prof_id = "777777";
let payment_method = "CARD";
let amount = "580.55";
let installmentPlanId = 1952;
let card_token = 'ac0a1909256e8bb5a35a6311c5e824c223d13ae877c5bb0419350b01c619d59d';
let cvv = 123;
let merchant_sec_key = "259af31fc2f74453b3a55739b21ae9ef";
let signature_body = merchantCode.concat(merchantCode , merchantRefNumber , merchant_cust_prof_id , payment_method , amount , card_token, cvv, installmentPlanId, 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,
'merchantRefNumber' : merchantRefNumber,
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'customerProfileId' : '777777',
'cardToken' : '4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1',
'cvv' : '123',
'amount' : '580.55',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : {
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
},
'installmentPlanId' : installmentPlanId,
'signature' : hash_signature,
'paymentMethod' : 'CARD',
'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==",
"merchantRefNumber" : "23124654641",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"customerProfileId" : "777777",
"cardToken" : "4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1",
"cvv" : 123,
"amount" : 580.55,
"currencyCode" : "EGP",
"language" : "en-gb",
"chargeItems" : {
"itemId" : "897fa8e81be26df25db592e81c31c",
"description" : "Item Description",
"price" : 580.55,
"quantity" : 1
},
"installmentPlanId" : 1952,
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"paymentMethod" : "CARD",
"description": "example description"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge");
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==",
"merchantRefNumber" : "23124654641",
"customerName" : "Ahmed Ali",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"customerProfileId" : "777777",
"cardToken" : "4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1",
"cvv" : 123,
"amount" : 580.55,
"currencyCode" : "EGP",
"language" : "en-gb",
"chargeItems" : {
"itemId" : "897fa8e81be26df25db592e81c31c",
"description" : "Item Description",
"price" : 580.55,
"quantity" : 1
},
"installmentPlanId" : 1952,
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"payment_method" : "CARD",
"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/charge", new fawrypay_request
{
merchantCode = "1tSa6uxz2nTwlaAmt38enA==",
merchantRefNumber = "23124654641",
customerName = "Ahmed Ali",
customerMobile = "01234567891",
customerEmail = "example@gmail.com",
customerProfileId = "777777",
cardToken = "4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1",
cvv = "123",
amount = "580.55",
currencyCode = "EGP",
language = "en-gb",
chargeItems = {
itemId = "897fa8e81be26df25db592e81c31c",
description = "Item Description",
price = 580.55,
quantity = 1
},
installmentPlanId = "1952",
signature = "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
payment_method = "CARD",
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 = "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 merchantRefNumber { get; set; }
public string signature { get; set; }
public string merchantCode { get; set; }
public string merchantRefNumber { get; set; }
public string customerName { get; set; }
public string customerMobile { get; set; }
public string customerEmail { get; set; }
public string customerProfileId { get; set; }
public string cardToken { get; set; }
public string cvv { get; set; }
public string amount { get; set; }
public string currencyCode { get; set; }
public string language { get; set; }
public ChargeItems chargeItems;
public string installmentPlanId { get; set; }
public string signature { get; set; }
public string payment_method { 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; }
}
}
Sample Request Data
{
"merchantCode": "1tSa6uxz2nTwlaAmt38enA==",
"customerMobile": "01234567891",
"customerEmail": "example@gmail.com",
"customerProfileId": "777777",
"cardToken": "4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1",
"cvv": "123",
"merchantRefNum": "2312465464",
"amount": "580.55",
"currencyCode": "EGP",
"language" : "en-gb",
"chargeItems": [
{
"itemId": "897fa8e81be26df25db592e81c31c",
"description": "Item Descriptoin",
"price": "580.55",
"quantity": "1"
}
],
"installmentPlanId" : 1952,
"signature": "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36",
"paymentMethod": "CARD",
"description": "Example Description"
}
FawryPay Sample Response
Whenever you call FawryPay installment charge using card token API, you may expect a response in the form of JSON object which contains all necessary payment processing information.
Sample Installment Charge using Card Token Payment API Response
Response Parameters Description
| Arguments | type | Description | example |
|---|---|---|---|
| type | String |
Type of response. | ChargeResponse |
| referenceNumber | String |
FawryPay issued transaction reference number. | 963455678 |
| merchantRefNumber | String |
Merchant issued transaction reference number. This is the same as the reference number you have set in your charge request. | 9990d0642040 |
| orderAmount | Decimal |
Order amount in two decimal places format. | 20.00 |
| paymentAmount | Decimal |
The paid amount in two decimal places format. | 20.00 |
| fawryFees | Decimal |
The payment processing fees. | 1.00 |
| paymentMethod | String |
Payment Method Selected by your client. | 'CashOnDelivery', 'PayAtFawry', 'MWALLET', 'CARD' or 'VALU' |
| orderStatus | String |
Order Status. | PAID |
| paymentTime | Integer |
Timestamp to record when the payment has been processed. | 1607879720568 |
| customerMobile | String |
Customer Mobile Number. | 01234567891 |
| customerMail | String |
Customer E-mail address. | example@email.com |
| authNumber | String |
Payment authentication number | 12336534 |
| 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 |
POSThttps://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/chargeResponse
// API Response Data Should Appear here
// This is a sample successful Response
{
"type": "ChargeResponse",
"referenceNumber": "963455678",
"merchantRefNumber": "9990d0642040",
"orderAmount": 20.00,
"paymentAmount": 20.00,
"fawryFees": 1.00,
"paymentMethod": "CARD",
"orderStatus": "PAID",
"paymentTime": 1607879720568,
"customerMobile": "01234567891",
"customerMail": "example@gmail.com",
"authNumber": "12336534",
"customerProfileId": "1212",
"signature": "b0ef178e2f06b215b18cfc7d82fb5d1f7b95dfcc91e33f8a6ce1e1251fdd04ec",
"statusCode": 200,
"statusDescription": "Operation done successfully"
}
4. Present Payment Result
After the client completes the payment and no further actions are
required on the front end or client app, use the statusCode to inform
the client about the payment status.
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 |
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.