3D Secure Authentication Card Payments
Learn how to create 3DS payments using clien's card information.
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 3D secure payments using cards. You will also learn how to create payment using a pre-saved cards' tokens of your clients for a more secure usage.
3D Secure, or 3 domains secure, is an authentication protocol that represents an additional layer of for online credit card transactions. It also provides protection from fraudulent card use for the seller and his acquiring bank, the cardholder and his card issuing bank, and Card Association's networks (Visa, MasterCard, Meeza).
How it works?
After a customer clicks the payment button, your server should send a 3DS payment request to FawryPay including your return URL. This return URL shall be used to redirect your client back to your application after completing payment authentication with the card issuer third party. FawryPay will respond with the redirect URL to which you will need to redirect your client for payment authentication. After redirect, your client will be redirected to the card issuer's authentication window to provide additional authentication data, for example a password or an SMS verification code, and confirm the card payment. This authentication is normally marked with MasterCard SecureCode or Verified by Visa or Meeza logos. There your customer needs to enter a personal password (or security code) which is verified by his/her card issuer. The payment authentication result of the card issuer bank shall be sent back to FawryPay which, in turn, will redirect your client to your provided return URL.
1. 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.
2. Make 3DS Card Payment
Depending on the payment method selected by your client, you may either proceed with with 3DS payment using card information or you may use a pre-saved card token to issue the payment. A detailed description of each method associated API is given below.
3DS Charge Request using Card POST
This API can be used to charge the client using his card information using 3DS authentication mechanism. 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, PayUsingCC, 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. | |
| enable3DS | Boolean |
required | Set to "true" to enable 3DS authentication. | |
| authCaptureModePayment | Boolean |
required | Set to "true" to enable authentication capture option. | |
| returnUrl | URL String |
required | After the card issuing bank process the authentication process, this will be the redirection URL where your customer will be redirected to. Example: "https://www.google.com/" | |
| 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 | |
| signature | String |
required | The SHA-256 digested for the following concatenated string "merchantCode + merchantRefNum + customerProfileId (if exists, otherwise "") + paymentMethod + amount (in two decimal format 10.00) + cardNumber + cardExpiryYear + cardExpiryMonth + cvv + returnUrl + secureKey" | |
An example call of card payment with an amount of 580.55EGP is given below.
function FawryPay3DSCard(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,
merchantRefNum : transaction_data.merchantRefNum,
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
}
],
enable3DS : true,
authCaptureModePayment : false,
returnUrl : "https://developer.fawrystaging.com",
signature : transaction_data.signature ,
paymentMethod : 'PayUsingCC' ,
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 = 'PayUsingCC';
$amount = '580.55';
$cardNumber = '4242424242424242',
$cardExpiryYear = '21';
$cardExpiryMonth = '05';
$cvv = 123;
$returnUrl = "https://www.google.com/";
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $merchantRefNum . $merchant_cust_prof_id . $payment_method .
$amount . $cardNumber . $cardExpiryYear . $cardExpiryMonth . $cvv . $returnUrl .$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,
'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'
],
'enable3DS' => true,
'authCaptureModePayment' => false,
'returnUrl' => $returnUrl,
'signature' => $signature,
'paymentMethod' => 'PayUsingCC',
'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
import json
# FawryPayAPI Endpoint
URL = "https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge"
# Payment Data
merchantCode = 'siYxylRjSPz4D7HfFGdKvQ=='
merchantRefNum = 'abc642043'
merchant_cust_prof_id = '777777'
payment_method = 'PayUsingCC'
amount = '580.55'
cardNumber = '4242424242424242'
cardExpiryYear = '22'
cardExpiryMonth = '05'
cvv = '123'
"returnUrl" :"https://developer.fawrystaging.com"
merchant_sec_key = '41327482-d361-46fa-a47f-f892b090f9ae' # For the sake of demonstration
#signature = hashlib.sha256(merchantCode + (merchantRefNum) + (merchant_cust_prof_id) + (payment_method) +
# (amount) + (cardNumber) + (cardExpiryYear) + (cardExpiryMonth) + (cvv) + (merchant_sec_key)).hexdigest()
#card_info= (merchantCode + merchantRefNum + merchant_cust_prof_id + payment_method +
# amount + cardNumber + cardExpiryYear + cardExpiryMonth + cvv + merchant_sec_key)
card_info = ""
card_info=card_info + (merchantCode + merchantRefNum + payment_method +
amount + cardNumber + cardExpiryYear + cardExpiryMonth + cvv +returnUrl+ merchant_sec_key)
print (card_info.encode())
signature = hashlib.sha256(str(card_info).encode('utf-8')).hexdigest()
#signature =hashlib.sha256(card_info.encode()).hexdigest()
# defining a params dict for the parameters to be sent to the API
PaymentData = {
"merchantCode":merchantCode,
"merchantRefNum":merchantRefNum,
"cardNumber": cardNumber,
"cardExpiryYear": cardExpiryYear,
"cardExpiryMonth": cardExpiryMonth,
"cvv": cvv,
"customerMobile": "01111111111",
"customerEmail": "a@gmail.com",
"amount": 580.55,
"currencyCode": "EGP",
"language" : "en-gb",
"returnUrl": returnUrl,
"chargeItems" : [
{
"itemId":"184",
"price":580.55,
"quantity":1
}
],
"enable3DS":True,
"paymentMethod": "CARD",
"signature":signature
}
print (json.dumps(PaymentData))
headers = {'Content-Type': 'application/json', 'Accept' : 'application/json'}
# sending post request and saving the response as response object
status_request = requests.post(URL, json.dumps(PaymentData),headers=headers)
print ('sent')
print (status_request.status_code)
print (status_request.text)
# 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 FawryPay3DSCard() {
let merchantCode = "1tSa6uxz2nTwlaAmt38enA==";
let merchantRefNum = "23124654641";
let merchant_cust_prof_id = "777777";
let payment_method = "PayUsingCC";
let amount = "580.55";
let cardNumber = "4242424242424242";
let cardExpiryYear = "21";
let cardExpiryMonth = "05";
let cvv = 123;
let merchant_sec_key = "259af31fc2f74453b3a55739b21ae9ef";
let returnUrl = 'https://www.google.com/';
let signature_body = merchantCode.concat(merchantCode , merchantRefNum , merchant_cust_prof_id , payment_method ,
amount , cardNumber , cardExpiryYear , cardExpiryMonth , cvv , returnUrl, 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',
'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'
},
'enable3DS' : true,
'authCaptureModePayment' : false,
'returnUrl' : returnUrl,
'signature' : hash_signature,
'paymentMethod' : 'PayUsingCC',
'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",
"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
},
"enable3DS" : true,
"authCaptureModePayment" : false,
"returnUrl" :"https://developer.fawrystaging.com",
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"paymentMethod" : "PayUsingCC",
"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==",
"merchantRefNum" : "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
},
"enable3DS" : true,
"authCaptureModePayment" : false,
"returnUrl" :"https://developer.fawrystaging.com",
"signature" : "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
"paymentMethod" : "PayUsingCC",
"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==",
merchantRefNum = "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
},
enable3DS = "true",
authCaptureModePayment = "false",
returnUrl = "https://www.google.com/",
signature = "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
payment_method = PayUsingCC,
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 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 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 enable3DS { get; set; }
public string authCaptureModePayment { get; set; }
public string returnUrl { 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"
}
],
"enable3DS" : true,
"authCaptureModePayment" : false,
"returnUrl" :"https://developer.fawrystaging.com",
"signature": "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36",
"paymentMethod": "CARD",
"description": "Example Description"
}
FawryPay Sample Response
Whenever you call FawryPay 3DS payment using card API, you may expect a response in the form of JSON object which contains all necessary payment processing information.
Sample 3DS Card Payment API Response
POSThttps://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge
Response
// API Response Data Should Appear here
// This is a sample successful Response
{
"type": "ChargeResponse",
"nextAction": {
"type": "THREE_D_SECURE",
"redirectUrl": "https://atfawry.fawrystaging.com/atfawry/plugin/3ds/7104048097"
},
"statusCode": 200,
"statusDescription": "Operation done successfully",
"basketPayment": false
}
3DS Charge Request using Card Token POST
This API can be used to charge the clients whose card information has been tokenized before, yet, through 3DS authentication mechanism. To Learn more about cards tokenization, please refer to Tokenization integration section. 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 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. | |
| cardToken | String |
required | Card Token. | |
| 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 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. | |
| enable3DS | Boolean |
required | Set to "true" to enable 3DS authentication. | |
| authCaptureModePayment | Boolean |
required | Set to "true" to enable authentication capture option. | |
| returnUrl | URL String |
required | After the card issuing bank process the authentication process, this will be the redirection URL where your customer will be redirected to. Example: "https://www.google.com/" | |
| 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 | |
| signature | String |
required | The SHA-256 digested for the following concatenated string "merchantCode + merchantRefNum + customerProfileId (if exists, otherwise "") + paymentMethod + amount (in two decimal format 10.00) + cardToken + cvv + returnUrl + secureKey" | |
An example call of 3DS card token payment with an amount of 580.55EGP is given below.
function FawryPay3DSCardToken(transaction_data) {
const PaymentData = {
merchantCode: transaction_data.merchantCode,
customerName: transaction_data.customerName,
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
}
],
enable3DS : true,
authCaptureModePayment : false,
returnUrl : "https://developer.fawrystaging.com",
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;
$returnUrl = "https://www.google.com/";
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $merchantRefNumber . $merchant_cust_prof_id . $payment_method . $amount . $card_token . $cvv . $returnUrl . $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',
'cardToken' => $card_token,
'cvv' => '123',
'amount' => '580.55',
'currencyCode' => 'EGP',
'language' => 'en-gb',
'chargeItems' => [
'itemId' => '897fa8e81be26df25db592e81c31c',
'description' => 'Item Description',
'price' => '580.55',
'quantity' => '1'
],
'enable3DS' => true,
'authCaptureModePayment' => false,
'returnUrl' => $returnUrl,
'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 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
returnUrl = 'https://www.google.com/'
card_token = 'ac0a1909256e8bb5a35a6311c5e824c223d13ae877c5bb0419350b01c619d59d'
merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef' // For the sake of demonstration
signature = hashlib.sha256(merchantCode + merchantRefNumber + merchant_cust_prof_id + payment_method + amount + card_token + cvv + returnUrl + 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',
'cardToken' : card_token,
'cvv' : '123',
'amount' : '580.55',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : {
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
},
'enable3DS' : true,
'authCaptureModePayment' : false,
'returnUrl' : 'https://www.google.com/',
'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 FawryPay3DSCardToken() {
let merchantCode = "1tSa6uxz2nTwlaAmt38enA==";
let merchantRefNumber = "23124654641";
let merchant_cust_prof_id = "777777";
let payment_method = "CARD";
let amount = "580.55";
let card_token = 'ac0a1909256e8bb5a35a6311c5e824c223d13ae877c5bb0419350b01c619d59d';
let cvv = 123;
let merchant_sec_key = "259af31fc2f74453b3a55739b21ae9ef";
let returnUrl = 'https://www.google.com/';
let signature_body = merchantCode.concat(merchantCode , merchantRefNumber , merchant_cust_prof_id , payment_method , amount , card_token, cvv, returnUrl, 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',
'cardToken' : card_token,
'cvv' : '123',
'amount' : '580.55',
'currencyCode' : 'EGP',
'language' : 'en-gb',
'chargeItems' : {
'itemId' : '897fa8e81be26df25db592e81c31c',
'description' : 'Item Description',
'price' : '580.55',
'quantity' : '1'
},
'enable3DS' : true,
'authCaptureModePayment' : false,
'returnUrl' : returnUrl,
'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",
"cardToken" : "ac0a1909256e8bb5a35a6311c5e824c223d13ae877c5bb0419350b01c619d59d",
"cvv" : 123,
"amount" : 580.55,
"currencyCode" : "EGP",
"language" : "en-gb",
"chargeItems" : {
"itemId" : "897fa8e81be26df25db592e81c31c",
"description" : "Item Description",
"price" : 580.55,
"quantity" : 1
},
"enable3DS" : true,
"authCaptureModePayment" : false,
"returnUrl" :"https://developer.fawrystaging.com",
"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
},
"enable3DS" : true,
"authCaptureModePayment" : false,
"returnUrl" :"https://developer.fawrystaging.com",
"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",
cardToken = "4f2f5dc87684fd67cb54c5dfbe30daec7e35e14265168db2a800c6553ef1aae1",
cvv = "123",
amount = "580.55",
currencyCode = "EGP",
language = "en-gb",
chargeItems = {
itemId = "897fa8e81be26df25db592e81c31c",
description = "Item Description",
price = 580.55,
quantity = 1
},
enable3DS = "true",
authCaptureModePayment = "false",
returnUrl = "https://www.google.com/",
signature = "3f527d0209f4fa5e370caf46f66597c6a7c04580c827ca1f29927ec0d9215131",
paymentMethod = "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 enable3DS { get; set; }
public string authCaptureModePayment { get; set; }
public string returnUrl { 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==",
"merchantRefNum": "2312465464",
"customerEmail": "example@gmail.com",
"customerProfileId": "1212",
"customerName": "example name",
"customerMobile": "01234567891",
"cardToken": "55757083c6fe56ee085023fa2f68970e44e9a988f75f621a47b95f9ac75fcb02",
"cvv": "123",
"amount": "580.55",
"currencyCode": "EGP",
"language" : "en-gb",
"chargeItems": [
{
"itemId": "897fa8e81be26df25db592e81c31c",
"description": "Item Descriptoin",
"price": "580.55",
"quantity": "1"
}
],
"enable3DS" : true,
"authCaptureModePayment" : false,
"returnUrl" :"https://developer.fawrystaging.com",
"signature": "986f05472a64ffdad4be1f4433bae313aa5301b26ca10c530d6d6a2784151c70",
"paymentMethod": "CARD",
"description": "Example Description"
}
FawryPay Sample Response
Whenever you call FawryPay payment using card token API, you should expect a response in the form of JSON object which contains all necessary payment processing information.
Sample 3DS Card Token Payment API Response
Response Parameters Description
POSThttps://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/charge
Response
// API Response Data Should Appear here
// This is a sample successful Response
{
"type": "ChargeResponse",
"nextAction": {
"type": "THREE_D_SECURE",
"redirectUrl": "https://atfawry.fawrystaging.com/atfawry/plugin/3ds/7104048097"
},
"statusCode": 200,
"statusDescription": "Operation done successfully",
"basketPayment": false
}
3. Redirect client to Card Issuer
After submitting a 3DS payment request to FawryPay, FawryPay will respond with the redirect URL to which you will need to redirect your client for payment
authentication. The redirect URL is incorporated in FawryPay response as described in the prevois section, redirectUrl.
After redirect, your client will be redirected to the card issuer's authentication
window to provide additional authentication data, for example a password or an SMS verification code,
and confirm the card payment. This authentication is normally marked with MasterCard SecureCode or
Verified by Visa or Meeza logos. There your customer needs to enter a personal password (or security code)
which is verified by his/her card issuer. The payment authentication result of the card issuer bank
shall be sent back to FawryPay which, in turn, will redirect your client to your provided return URL.
4. Present Payment Result
After the client completes the payment and no further actions are required on the front end or client app. To inform your client about the payment status, you can use one of the following options:
-
Using Charge Response: The charge response shall be appended to your return URL. Validate the charge response received from FawryPay system using the response signature and
, then, you may use the status code and status description to inform your client about the payment status.
Illustration of the URL parameters:
Detailed Description of Charge Response Parameters
Arguments type Description example type StringType of response. ChargeResponse referenceNumber StringFawryPay issued transaction reference number. 963455678 merchantRefNumber StringMerchant issued transaction reference number. This is the same as the reference number you have set in your charge request. 9990d0642040 orderAmount DecimalOrder amount in two decimal places format. 20.00 paymentAmount DecimalThe paid amount in two decimal places format. 20.00 fawryFees DecimalThe payment processing fees. 1.00 paymentMethod StringPayment Method Selected by your client. 'CashOnDelivery', 'PayAtFawry', 'MWALLET', 'PayUsingCC' or 'VALU' orderStatus StringOrder Status. PAID paymentTime IntegerTimestamp to record when the payment has been processed. 1607879720568 customerMobile StringCustomer Mobile Number. 01234567891 customerMail StringCustomer E-mail address. example@email.com customerProfileId StringCustomer Profile ID in the merchant's system. 1212 signature StringResponse 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 StringResponse status code. 200 statusDescription StringResponse status description. Operation done successfully - Using Get Payment Status API: You may pull the status of a particular payment anytime using get payment status API.
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.