Create and Use Card Tokens
Generate and Make Payments using card tokens.
Throughout this page, you will learn how to:
Create Card Token
In this section, you will learn how to create card tokens for your clients using either our create card token API
or our web-client card tokenization plugin.
The merchant can use this API to store the customer cards' information in a secured PCI environment. Once you trigger this API, FawryPay will send you back the generated card token for you to store in your records to use in future payments. You can also save multiple cards for the same user using the this API.
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. |
| customerProfileId | Integer |
required | The unique customer profile ID in merchant system. This can be the user ID. |
| customerMobile | String |
required | The customer mobile in merchant system: 01xxxxxxx |
| customerEmail | Email String |
required | The customer e-mail in merchant system. |
| cardNumber | Integer |
required | 12 Digits Card number. |
| cardAlias | String |
required | Customer name on the card or any alias. |
| expiryYear | Integer |
required | The two digit format for the card expiry year for example 21. |
| expiryMonth | Integer |
required | The two digit format for the card expiry month for example 05. |
| cvv | Integer |
required | 3 Digits card CVV. |
| isDefault | Boolean |
required | Defines if this card is default one or not |
| enable3ds | Boolean |
required | Set to "true" to enable 3DS authentication. |
| returnUrl | URL String |
required | Any URL Fawry can redirect the customer back to , Fawry will add "statusCode" and "statusDescription" as a query params to the end of that url, e.g: https://www.your-web-site.domain/any-path?statusCode=200&statusDescription=Operation Done. |
An example call of create card token API is given below.
function FawryCreateCardToken(transaction_data) {
const RequestData = {
merchantCode: transaction_data.merchantCode,
customerProfileId : transaction_data.customerProfileId,
customerMobile : transaction_data.customerMobile,
customerEmail : transaction_data.customerEmail,
cardNumber : transaction_data.cardNumber,
cardAlias : transaction_data.cardAlias,
expiryYear : transaction_data.expiryYear,
expiryMonth : transaction_data.expiryMonth,
cvv : transaction_data.cvv,
enable3ds : true,
isDefault : true,
returnUrl : "https://developer.fawrystaging.com",
};
// Use fetch to send the Request Data to FawryPay Create Card Token API.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/fawrypay-api/api/cards/cardToken', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(RequestData),
});
// Return and display the result of the charge.
return response.json();
}
$merchantCode = '1tSa6uxz2nRbgY+b+cZGyA==';
$returnUrl = "https://developer.fawrystaging.com";
$httpClient = new \GuzzleHttp\Client(); // guzzle 6.3
$response = $httpClient->request('POST', 'https://atfawry.fawrystaging.com/fawrypay-api/api/cards/cardToken', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json'
],
'body' => json_encode( [
'merchantCode' => $merchantCode,
'customerProfileId'=> '777777',
'customerMobile' => '01234567891',
'customerEmail' => 'example@gmail.com',
'cardNumber' => '4242424242424242',
'cardAlias' => 'customer name on the card or any alias',
'expiryYear' => '21',
'expiryMonth' => '05',
'cvv' => '123',
'enable3ds' => true,
'isDefault' => true,
'returnUrl' => $returnUrl,
] , 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 Create Card Token API Endpoint
URL = "https://atfawry.fawrystaging.com/fawrypay-api/api/cards/cardToken"
# Payment Data
merchantCode = '1tSa6uxz2nRbgY+b+cZGyA=='
# defining a params dict for the parameters to be sent to the API
PaymentData = {
'merchantCode' : merchantCode,
'customerProfileId' : '777777',
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'cardNumber' : '4242424242424242',
'cardAlias' : 'customer name on the card or any alias',
'expiryYear' : '21',
'expiryMonth' : '05',
'cvv' : '123',
'enable3ds' : true,
'isDefault' : true,
'returnUrl' : 'https://developer.fawrystaging.com',
}
# 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 FawryCreateCardToken() {
let merchantCode = "1tSa6uxz2nRbgY+b+cZGyA==";
let returnUrl = 'https://developer.fawrystaging.com'
axios.post('https://atfawry.fawrystaging.com/fawrypay-api/api/cards/cardToken', {
'merchantCode' : merchantCode,
'customerProfileId' : '777777',
'customerMobile' : '01234567891',
'customerEmail' : 'example@gmail.com',
'cardNumber' : '4242424242424242',
'cardAlias' : 'customer name on the card or any alias',
'expiryYear' : '21',
'expiryMonth' : '05',
'cvv' : '123',
'enable3ds' : true,
'isDefault' : true,
'returnUrl' : returnUrl,
})
.then(response => {
// Get Response Contents
let type = response.data.type;
let paymentStatus = response.data.statusCode;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/fawrypay-api/api/cards/cardToken \
-H "content-type: application/json" \
-X POST \
-d "{
"merchantCode" : "1tSa6uxz2nRbgY+b+cZGyA==",
"customerProfileId" : "777777",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"cardNumber" : "4242424242424242",
"cardAlias" : "customer name on the card or any alias",
"expiryYear" : "21",
"expiryMonth" : "05",
"cvv" : 123,
"enable3ds" : true,
"isDefault" : true,
"returnUrl" : "https://developer.fawrystaging.com",
}"
URL url = new URL ("https://atfawry.fawrystaging.com/fawrypay-api/api/cards/cardToken");
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" : "1tSa6uxz2nRbgY+b+cZGyA==",
"customerProfileId" : "777777",
"customerMobile" : "01234567891",
"customerEmail" : "example@gmail.com",
"cardNumber" : "4242424242424242",
"cardAlias" : "customer name on the card or any alias",
"expiryYear" : "21",
"expiryMonth" : "05",
"cvv" : 123,
"enable3ds" : true,
"isDefault" : true,
"returnUrl" : "https://developer.fawrystaging.com",
}";
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/fawrypay-api/api/cards/cardToken", new fawrypay_request
{
merchantCode = "1tSa6uxz2nRbgY+b+cZGyA==",
customerProfileId = "777777",
customerMobile = "01234567891",
customerEmail = "example@gmail.com",
cardNumber = "4242424242424242",
cardAlias = "customer name on the card or any alias",
expiryYear = "21",
expiryMonth = "05",
cvv = 123,
enable3ds = "true",
isDefault = "true",
returnUrl = "https://developer.fawrystaging.com",
});
}
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 customerProfileId { get; set; }
public string customerMobile { get; set; }
public string customerEmail { get; set; }
public string cardNumber { get; set; }
public string cardAlias { get; set; }
public string expiryYear { get; set; }
public string expiryMonth { get; set; }
public string cvv { get; set; }
public string enable3ds { get; set; }
public string isDefault { get; set; }
public string returnUrl { 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":"1tSa6uxz2nRbgY+b+cZGyA==",
"customerProfileId": "777777",
"customerMobile":"01234567891",
"customerEmail":"customer-mail@domain.com",
"cardNumber":"4242424242424242",
"cardAlias" : "customer name on the card or any alias",
"expiryYear":"23",
"expiryMonth":"05",
"cvv":123,
"isDefault":true,
"enable3ds":true,
"returnUrl":"https://developer.fawrystaging.com"
}
FawryPay Sample Response
Whenever you trigger create card token API, you may expect a response in the form of JSON object which contains token creation processing information.
Sample Create Card Token API Response
Response Parameters Description
| Parameter | type | Description | Example | |
|---|---|---|---|---|
| type | String |
Response Type | CardTokenResponse | |
| nextAction
|
||||
| type | String |
The type of response. | THREE_D_SECURE | |
| redirectUrl | URL String |
Redirect URL for you to redirect your client for payment authentication. | https://atfawry.fawrystaging.com/atfawry/plugin/3ds/T-1004644 | |
| card
|
||||
| token | String |
The generated card token to be used in future charges | c44f3f20d92e..... | |
| creationDate | Integer |
Timestamp of the token creation date. | 1514744801948 | |
| lastFourDigits | Integer |
The last four digits of the card | 1234 | |
| firstSixDigits | Integer |
The first six digits of the card | 400555 | |
| brand | String |
The card issuer brand name | VISA - Master Card | |
| statusCode | Integer |
The response status code | 200 | |
| statusDescription | String |
required | Operation done successfully | |
POSThttps://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/chargeResponse
// API Response Data Should Appear here
// This is a sample successful Response
{
"type":"CardTokenResponse",
"card": {
"token":"c44f3f20d92e5fb1239e515e7a3736a2a94117151896d3c314de931b5d0fc80a",
"creationDate": 1514744801948,
"lastFourDigits":"0001",
"brand":"Visa Card"
},
"statusCode":200,
"statusDescription":"Operation done successfully"
}
Leaving no one behind, FawryPay introduces the web client card tokenization plugin for non fully PCI Compliant merchants. The merchant can use this service to store the customer cards information in our secured PCI environment. Then, merchants can use the returned token in the charge request to save multiple cards for the same user. You can trigger FawryPay web client card tokenization plugin by redirecting your user, or you may simply iFrame the plugin within your checkout page, to our plugin endpoint:
SandBox Environment
Production Environment
Example Call for Web Client Card Tokenization Plugin
key - value list:
{
"card": {
"token":"c44f3f20d92e5fb1239e515e7a3736a2a94117151896d3c314de931b5d0fc80a",
"creationDate": 1514744801948,
"lastFourDigits":"0001",
"firstSixDigits":"400555",
"brand":"Visa Card"
},
"statusCode":200,
"statusDescription":"Operation done successfully"
}
The following table contains an illustration for the parameters that you need to associate with your plugin call.
| Arguments | Required | type | Description | example |
|---|---|---|---|---|
| accNo | required | String |
The merchant code provided by FawryPay | is0N+YQzlE4= |
| customerProfileId | required | String |
The Customer profile ID at the merchant system | 123 |
| returnUrl | required | URL String |
A URL string where you wish FawryPay plugin to redirect after finish the process. | https://www.your-web-site.domain/any-path?statusCode=200&statusDescription=Operation Done |
| locale | Optional | String |
decides the language that the Tokenization Plugin UI would be displaied with. | "en" or "ar" |
What's next?
Once you have triggered the Web Client card tokenization plugin, the plugin will redirect your client returnUrl associated with your request. Whenever you want to get a list of your saved card tokens, you can user our Manage Card Tokens APIs.
Pay with Card Token
Charge Request using Card Token POST
This API can be used to charge the clients whose card information has been tokenized before. 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 | |
| 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 | |
| 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 exists, otherwise "") + paymentMethod + amount (in two decimal format 10.00) + cardToken + cvv + returnUrl + secureKey" | |
An example call of card token payment with an amount of 580.55EGP is given below.
function FawryPayWithCardToken(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
}
],
signature : transaction_data.signature ,
paymentMethod : 'CARD' ,
description : 'transaction description'
};
// Use fetch to send the Payment Data to FawryPay Pay with Card Token API.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/ECommerceWeb/Fawry/payments/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;
$merchant_sec_key = '259af31fc2f74453b3a55739b21ae9ef'; // For the sake of demonstration
$signature = hash('sha256' , $merchantCode . $merchantRefNumber . $merchant_cust_prof_id . $payment_method . $amount . $card_token . $cvv . $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'
],
'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
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 + 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'
},
'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 FawryPayWithCardToken() {
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 signature_body = merchantCode.concat(merchantCode , merchantRefNumber , merchant_cust_prof_id , payment_method , amount , card_token, cvv, 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'
},
'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
},
"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
},
"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
},
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 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 name",
"customerMobile": "01234567891",
"customerEmail": "example@gmail.com",
"customerProfileId": "777777",
"cardToken": "ac0a1909256e8bb5a35a6311c5e824c223d13ae877c5bb0419350b01c619d59d",
"cvv": "123",
"merchantRefNum": "2312465464",
"amount": "580.55",
"currencyCode": "EGP",
"language" : "en-gb",
"chargeItems": [
{
"itemId": "897fa8e81be26df25db592e81c31c",
"description": "Item Descriptoin",
"price": "580.55",
"quantity": "1"
}
],
"signature": "2ca4c078ab0d4c50ba90e31b3b0339d4d4ae5b32f97092dd9e9c07888c7eef36",
"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 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"
}
Error Handling
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. |
| 9910 | Blank or invalid client's mobile number. |
| 9919 | Invalid card date. |
| 9944 | Customer profile or card token is empty. |
| 9946 | Blank or invalid signature. |
Next steps
Manage Card Tokens.
Optional
Take control over your clients' stored card tokens.
Set up payment notifications
Recommended
Whenever a transaction status has been updated, FawryPay will keep you informed.
End-to-End Testing
Before accepting live payments, you can use the cards and payment method details on this page to test 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.