Pay By Link (E-Invoice) - Using our APIS
if you already have your own dashboard and you want to generate e-invoices for your clients , you can login to fawry and generat e-invoices using our APIS
Add Payment Link API
you can pay with payment link usink Payment Link 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 | |
|---|---|---|---|---|
| sendingDate | String |
required | This is the due date of invoice. | |
| expiryDate | String |
required | Expiration date. | |
| note | String |
required | description, what customer exactly pay for. | |
| releaseDate | String |
required | If merchant want to issue invoice with different date rather than sending date. | |
| alertMerchantUponExpiry | Boolean |
optional | In case merchant need to receive email once invoice expired, (default is false). | |
| requiredCustomerData
|
||||
| id | integer |
required | Lookup ID. | |
| code | String |
required | Lookup Code. Possible values NAME - EMAIL - MOBILE_NUMBER - ADDRESS - NNATIONAL_ID - BIRTHDATE - GENDER - DELIVERY_DATE | |
| nameAr | String |
required | Lookup Name in Arabic depending on the selected code. (اسم العميل - البريد الالكتروني -الهاتف - االعنوان - بطافة الرقم القومي - تاريخ الميلاد - النوع - تاريخ التسليم) | |
| nameEn | String |
required | Lookup Name in English depending on the selected code. (Customer name - Email - Mobile number - Address - National ID - Birthdate - Gender - Delivery date) | |
| discount
|
||||
| value | integer |
required | value of the discount. | |
| type | String |
required | values: “FLAT” or “PERCENTAGE”. | |
| taxes | String |
optional | Percentage value by max 100. | |
| amount | double |
required | The total amount, in case there is no items. | |
| items
|
||||
| itemCode | String |
required | Code of the item. | |
| purchasedQuantity | integer |
required | Quantity of items. | |
| price | double |
required | Price of the item. | |
| nameEn | String |
required | Name or description of the item in English. | |
| nameAr | String |
required | Name or description of the item in Arabic. | |
| preferredPaymentMethod | String |
optional | •Values:
• PayAtFawry • CARD • VALU • Or any other payment method that allowed for merchant. |
|
Sample API Calls
An example call of Payment Link API is given below.
function add_payment_link(transaction_data) {
const paymentLink = {
sendingDate: transaction_data.sendingDate,
expiryDate: transaction_data.expiryDate,
note: transaction_data.note,
releaseDate: transaction_data.releaseDate,
alertMerchantUponExpiry: transaction_data.alertMerchantUponExpiry,
requiredCustomerData: transaction_data.requiredCustomerData,
discount: transaction_data.discount,
taxes: transaction_data.taxes,
amount: transaction_data.amount,
items: transaction_data.items,
preferredPaymentMethod: transaction_data.preferredPaymentMethod,
};
// Use fetch to send request data to FawryPay Payment Link API.
// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
const response = await fetch('https://atfawry.fawrystaging.com/invoice-api/invoices/payment-link', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + transaction_data.token, // The token you obtained from the login API
},
body: JSON.stringify(paymentLink),
});
// Return and display the result of the charge.
return response.json();
}
$sendingDate= "2021-02-27";
$expiryDate= "2021-02-28T13:19:17.000Z";
$note= "invoice description";
$releaseDate= "2021-02-27T13:16:50.668Z";
$alertMerchantUponExpiry= "false";
$requiredCustomerData= [
[ "id"=> 1,
"code"=> "NAME",
"nameAr"=> "اسم العميل",
"nameEn"=> "Customer name"],
[
"id"=> 3,
"code"=> "MOBILE_NUMBER",
"nameAr"=> "الهاتف",
"nameEn"=> "Mobile number"]
];
$discount= [
"value"=> 20,
"type"=> "FLAT"
];
$taxes= 0;
$amount= 150.75;
$items= [
"nameEn"=> "description 1",
"nameAr"=> "description 1",
"itemCode"=> "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity"=> 2,
"price"=> 150.75,
];
$preferredPaymentMethod="PayAtFawry";
$response =request('POST', 'https://atfawry.fawrystaging.com/invoice-api/invoices/payment-link', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer ' + $token, // The token you obtained from the login API
],
'body' => json_encode( [
'requiredCustomerData' => requiredCustomerData,
'amount' => $amount,
'sendingDate' => $sendingDate,
'expiryDate' => $expiryDate,
'releaseDate' => $releaseDate,
'note' => $note,
'alertMerchantUponExpiry' => $alertMerchantUponExpiry,
'discount' => $discount,
'items' => $items,
'taxes' => $taxes,
'preferredPaymentMethod' => $preferredPaymentMethod,
] , true)
]);
$response = json_decode($response->getBody()->getContents(), true);
$paymentLink = $response['type']; // post response values
# importing the requests library
import requests
# importing Hash Library
import hashlib
# FawryPay add payment link API Endpoint
URL = "https://atfawry.fawrystaging.com/invoice-api/invoices/payment-link"
# Data
sendingDate= '2021-02-27'
expiryDate= '2021-02-28T13:19:17.000Z'
releaseDate= '2021-02-27T13:16:50.668Z'
note= 'invoice description'
alertMerchantUponExpiry= 'false'
requiredCustomerData= [
{
"id": 1,
"code": "NAME",
"nameAr": "اسم العميل",
"nameEn": "Customer name"
},
{
"id": 3,
"code": "MOBILE_NUMBER",
"nameAr": "الهاتف",
"nameEn": "Mobile number"
}
]
discount= [
"value" : "20",
"type" : "FLAT"
]
amount= 150.75
taxes= 0
items= [
"itemCode" : "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity" : 2,
"price" : 150.75,
"nameEn" : "description 1",
"nameAr" : "description 1",
]
preferredPaymentMethod ='PayAtFawry'
# defining a params dict for the parameters to be sent to the API
paymentLink = {
'requiredCustomerData' : requiredCustomerData,
'amount' : amount,
'sendingDate' : sendingDate,
'expiryDate' : expiryDate,
'releaseDate' : releaseDate,
'note' : note,
'alertMerchantUponExpiry' : alertMerchantUponExpiry,
'discount' : discount,
'items' : items,
'taxes' : taxes,
'preferredPaymentMethod' : preferredPaymentMethod,
}
# sending post request and saving the response as response object
status_request = requests.post(url = URL, params = json.dumps(paymentLink),
headers={'Content-Type':'application/json',
'Authorization': 'Bearer {}'.AccessToken}//The token you obtained from the login API
)
# extracting data in json format
status_response = status_request.json()
function add_payment_link() {
let sendingDate= '2021-02-27';
let expiryDate= '2021-02-28T13:19:17.000Z';
let releaseDate= '2021-02-27T13:16:50.668Z';
let note= 'invoice description';
let alertMerchantUponExpiry= 'false';
let requiredCustomerData= [
{
"id": 1,
"code": "NAME",
"nameAr": "اسم العميل",
"nameEn": "Customer name"
},
{
"id": 3,
"code": "MOBILE_NUMBER",
"nameAr": "الهاتف",
"nameEn": "Mobile number"
}
];
let discount= [
"value" : "20",
"type" : "FLAT"
];
let taxes= 0;
let amount= 150.75;
let items= [
"nameEn" : "description 1",
"nameAr" : "description 1",
"price" : 150.75,
"discount" : [
"value" : "20",
"type" : "FLAT"
]
];
let preferredPaymentMethod ='PayAtFawry';
axios.post('https://atfawry.fawrystaging.com/invoice-api/invoices/payment-link', {
'requiredCustomerData' : requiredCustomerData,
'amount' : amount,
'sendingDate' : sendingDate,
'expiryDate' : expiryDate,
'releaseDate' : releaseDate,
'note' : note,
'alertMerchantUponExpiry' : alertMerchantUponExpiry,
'discount' : discount,
'items' : items,
'taxes' : taxes,
'preferredPaymentMethod' : preferredPaymentMethod,
},
headers: {
'Authorization': `Bearer AccessToken` //The token you obtained from the login API
}
)
.then(response => {
// post Response Contents
let paymentLink = response.data.paymentLink;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/invoice-api/invoices/payment-link\
-H "content-type: application/json , Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-d "{
"sendingDate": "2021-02-27",
"expiryDate": "2021-03-10T21:20:00.000Z",
"note": "invoice description",
"releaseDate": "2021-02-27T21:19:55.917Z",
"alertMerchantUponExpiry": "false",
"requiredCustomerData": [
{
"id": 1,
"code": "NAME",
"nameAr": "اسم العميل",
"nameEn": "Customer name"
},
{
"id": 3,
"code": "MOBILE_NUMBER",
"nameAr": "الهاتف",
"nameEn": "Mobile number"
}
],
"discount": {
"type": "FLAT",
"value": 5.00
},
"taxes": 0,
"amount": 250.5,
"items": [
{
"nameEn": "description 1",
"nameAr": "description 1",
"itemCode": "1cf4fc51ba984471ac3a063dfd7c6f4f",
"price": 250.5,
"purchasedQuantity": 1
}
],
"preferredPaymentMethod":"PayAtFawry"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/invoice-api/invoices/payment-link");
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestproperty("Authorization","Bearer " + AccessToken); //The token you obtained from the login API
con.setRequestProperty("Accept", "application/json");
con.setDoOutput(true);
String jsonInputString = "{
"sendingDate": "2021-02-27",
"expiryDate": "2021-03-10T21:20:00.000Z",
"note": "invoice description",
"releaseDate": "2021-02-27T21:19:55.917Z",
"alertMerchantUponExpiry": "false",
"requiredCustomerData": [
{
"id": 1,
"code": "NAME",
"nameAr": "اسم العميل",
"nameEn": "Customer name"
},
{
"id": 3,
"code": "MOBILE_NUMBER",
"nameAr": "الهاتف",
"nameEn": "Mobile number"
}
],
"discount": {
"type": "FLAT",
"value": 5.00
},
"taxes": 0,
"amount": 250.5,
"items": [
{
"nameEn": "description 1",
"nameAr": "description 1",
"itemCode": "1cf4fc51ba984471ac3a063dfd7c6f4f",
"price": 250.5,
"purchasedQuantity": 1
}
],
"preferredPaymentMethod":"PayAtFawry"
}";
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/invoice-api/invoices/payment-link", new invoice_request
{
requiredCustomerData= {
{
"id": 1,
"code": "NAME",
"nameAr": "اسم العميل",
"nameEn": "Customer name"
},
{
"id": 3,
"code": "MOBILE_NUMBER",
"nameAr": "الهاتف",
"nameEn": "Mobile number"
}
},
amount= 150.75,
sendingDate= "2021-02-27",
expiryDate= "2021-02-28T13:19:17.000Z",
releaseDate= "2021-02-27T13:16:50.668Z",
businessReference= "145556",
note= "invoice description",
alertMerchantUponExpiry= "false",
items= [
{
itemCode= "b2f35ed2d39e462abd5e4b1129a7305d",
purchasedQuantity= 2,
price= 150.75,
discount= {
value= 20,
type= "FLAT"
}
}
],
paymentType= "PUSH_TO_CUSTOMER",
taxes= 0,
preferredPaymentMethod= "PayAtFawry"
});
}
private static void PostJson(string uri, invoice_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.Headers.Add("Authorization", "Bearer " + AccessToken);//The token you obtained from the login API
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("POST failed. Received HTTP {0}", httpWebResponse.StatusCode);
throw new ApplicationException(message);
}
}
}
public class invoice_request
{
public string[] requiredCustomerData { get; set; };
public double amount { get; set; };
public string sendingDate { get; set; };
public string expiryDate { get; set; };
public string releaseDate { get; set; };
public string businessReference { get; set; };
public string note { get; set; };
public boolean alertMerchantUponExpiry { get; set; };
public string[] items { get; set; };
public string paymentType { get; set; };
public double taxes { get; set; };
public string preferredPaymentMethod { get; set; };
}
}
Request Parameters
Regardless of the choice of your preferred language, any of the code snippets above should produce an POST request containing the following JSON object in the request header:
{
"sendingDate": "2021-02-27",
"expiryDate": "2021-03-10T21:20:00.000Z",
"note": "invoice description",
"releaseDate": "2021-02-27T21:19:55.917Z",
"alertMerchantUponExpiry": "false",
"requiredCustomerData": [
{
"id": 1,
"code": "NAME",
"nameAr": "اسم العميل",
"nameEn": "Customer name"
},
{
"id": 3,
"code": "MOBILE_NUMBER",
"nameAr": "الهاتف",
"nameEn": "Mobile number"
}
],
"discount": {
"type": "FLAT",
"value": 5.00
},
"taxes": 0,
"amount": 250.5,
"items": [
{
"nameEn": "description 1",
"nameAr": "description 1",
"itemCode": "1cf4fc51ba984471ac3a063dfd7c6f4f",
"price": 250.5,
"purchasedQuantity": 1
}
],
"preferredPaymentMethod":"PayAtFawry"
}
Response Parameters
FawryPay Sample Response
Whenever you call FawryPay Payment Link API, you may expect a response in the form of JSON object which contains all payment processing information.
Sample Payment Link API Response
Response Parameters Description
| Parameter | type | Description | example |
|---|---|---|---|
| Invoice no. | String |
No. of the added invoice. | 4776211 |
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 |
|---|---|
| 201 | Created successfully. |
| 400 | Bad request. |
POSThttps://atfawry.fawrystaging.com/invoice-api/invoices/payment-link
// please run login API and put your token in the token field below Response
// API Response Data Should Appear here
// This is a sample successful Response
{
4776211
}
Was this page helpful?
Thank you for helping improve FawryPay's documentation. If you need help or have any questions, please consider contacting support.