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 Single Invoice API
You can pay a single invoice using Single Invoice 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 | |
|---|---|---|---|---|
| customer
|
||||
| name | String |
required | Name of the customer. | |
String |
optional | E-mail of the customer, required only in case communication method set to email or both - string. | ||
| mobile | String |
required | Mobile of the customer. | |
| amount | double |
required | The total amount, in case there is no items. | |
| sendingDate | String |
required | This is the due date of invoice. | |
| expiryDate | String |
required | Expiration date. | |
| releaseDate | String |
required | If merchant want to issue invoice with different date rather than sending date. | |
| businessReference | String |
optional | The reference number of invoice in merchant system. Must be unique per (amount- sending date) so invoice is duplicate only if you added it with the same business reference, amount and sending date.. | |
| note | String |
required | description, what customer exactly pay for. | |
| communicationLang | String |
optional | Values : “en-gb” or “ar-eg” , (default is English). | |
| communicationMethod | String |
optional | Values : “SMS”, “EMAIL”, “BOTH” , or “NONE” to stop sending any notification for the customer (default is SMS). | |
| alertMerchantUponExpiry | Boolean |
optional | In case merchant need to receive email once invoice expired, (default is false). | |
| items
|
||||
| itemCode | String |
required | Code of the item. | |
| purchasedQuantity | integer |
required | Quantity of items. | |
| price | double |
required | Price of the item. | |
| discount | String |
optional | optional – JSON object containing "value" and "type" of the discount. | |
| nameEn | String |
required | Name or description of the item in English. | |
| nameAr | String |
required | Name or description of the item in Arabic. | |
| paymentType | String |
optional | • Values: “PUSH_TO_CUSTOMER” or “PUSH_TO_FAWRY_PAY” • PUSH_TO_CUSTOMER: customer will receive SMS contains link to pay invoice through it. • PUSH_TO_FAWRY_PAY: customer will receive SMS contains order reference number and can pay it through fawry retails. . |
|
| taxes | String |
optional | Percentage value by max 100. | |
| preferredPaymentMethod | String |
optional | •Values:
• PayAtFawry • CARD • VALU • Or any other payment method that allowed for merchant. |
|
Sample API Calls
An example call of singleInvoice API for an amount of 362.50EGP is given below.
function add_single_invoice(transaction_data) {
const singleInvoice = {
customer: transaction_data.customer,
amount: transaction_data.amount,
sendingDate: transaction_data.sendingDate,
expiryDate: transaction_data.expiryDate,
releaseDate: transaction_data.releaseDate,
businessReference: transaction_data.businessReference,
note: transaction_data.note,
communicationLang: transaction_data.communicationLang,
communicationMethod: transaction_data.communicationMethod,
alertMerchantUponExpiry: transaction_data.alertMerchantUponExpiry,
items: transaction_data.items,
paymentType: transaction_data.paymentType,
taxes: transaction_data.taxes,
preferredPaymentMethod: transaction_data.preferredPaymentMethod,
};
// Use fetch to send request data to FawryPay Single Invoice 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/single', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + transaction_data.token, // The token you obtained from the login API
},
body: JSON.stringify(singleInvoice),
});
// Return and display the result of the charge.
return response.json();
}
$customer= [
"name"=> "your customer name",
"email"=> "mail@domain.com",
"mobile"=> "01234567899"
];
$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";
$communicationLang= "en-gb";
$communicationMethod= "SMS";
$alertMerchantUponExpiry= "false";
$items= [
"itemCode"=> "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity"=> 2,
"price"=> 150.75,
"discount"=> [
"value"=> 20,
"type"=> "FLAT"
]
];
$paymentType= "PUSH_TO_CUSTOMER";
$taxes= 0;
$preferredPaymentMethod="CARD";
$response =request('POST', 'https://atfawry.fawrystaging.com/invoice-api/invoices/single', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer ' + $token, // The token you obtained from the login API
],
'body' => json_encode( [
'customer' => $customer,
'amount' => $amount,
'sendingDate' => $sendingDate,
'expiryDate' => $expiryDate,
'releaseDate' => $releaseDate,
'businessReference' => $businessReference,
'note' => $note,
'communicationLang' => $communicationLang,
'communicationMethod' => $communicationMethod,
'alertMerchantUponExpiry' => $alertMerchantUponExpiry,
'items' => $items,
'paymentType' => $paymentType,
'taxes' => $taxes,
'preferredPaymentMethod' => $preferredPaymentMethod,
] , true)
]);
$response = json_decode($response->getBody()->getContents(), true);
$singleInvoice = $response['type']; // post response values
# importing the requests library
import requests
# importing Hash Library
import hashlib
# FawryPay add single invoice API Endpoint
URL = "https://atfawry.fawrystaging.com/invoice-api/invoices/single"
# invoice Data
customer= [
"name" : "your customer name",
"email" : "mail@domain.com",
"mobile" : "01234567899"
]
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'
communicationLang= 'en-gb'
communicationMethod= 'SMS'
alertMerchantUponExpiry= 'false'
items= [
"itemCode" : "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity" : 2,
"price" : 150.75,
"nameEn" : "description 1",
"nameAr" : "description 1",
"discount" : [
"value" : "20",
"type" : "FLAT"
]
]
paymentType= 'PUSH_TO_CUSTOMER'
taxes= 0
preferredPaymentMethod ='CARD'
# defining a params dict for the parameters to be sent to the API
singleInvoice = {
'customer' : customer,
'amount' : amount,
'sendingDate' : sendingDate,
'expiryDate' : expiryDate,
'releaseDate' : releaseDate,
'businessReference' : businessReference,
'note' : note,
'communicationLang' : communicationLang,
'communicationMethod' : communicationMethod,
'alertMerchantUponExpiry' : alertMerchantUponExpiry,
'items' : items,
'paymentType' : paymentType,
'taxes' : taxes,
'preferredPaymentMethod' : preferredPaymentMethod,
}
# sending post request and saving the response as response object
status_request = requests.post(url = URL, params = json.dumps(singleInvoice),
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_single_invoice() {
let customer= [
"name" : "your customer name",
"email" : "mail@domain.com",
"mobile" : "01234567899"
];
let amount= 150.75;
let sendingDate= '2021-02-27';
let expiryDate= '2021-02-28T13:19:17.000Z';
let releaseDate= '2021-02-27T13:16:50.668Z';
let businessReference= '145556';
let note= 'invoice description';
let communicationLang= 'en-gb';
let communicationMethod= 'SMS';
let alertMerchantUponExpiry= 'false';
let items= [
"itemCode" : "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity" : 2,
"price" : 150.75,
"nameEn" : "description 1",
"nameAr" : "description 1",
"discount" : [
"value" : "20",
"type" : "FLAT"
]
];
let paymentType= 'PUSH_TO_CUSTOMER';
let taxes= 0;
let preferredPaymentMethod ='CARD';
axios.post('https://atfawry.fawrystaging.com/invoice-api/invoices/single', {
'customer' : customer,
'amount' : amount,
'sendingDate' : sendingDate,
'expiryDate' : expiryDate,
'releaseDate' : releaseDate,
'businessReference' : businessReference,
'note' : note,
'communicationLang' : communicationLang,
'communicationMethod' : communicationMethod,
'alertMerchantUponExpiry' : alertMerchantUponExpiry,
'items' : items,
'paymentType' : paymentType,
'taxes' : taxes,
'preferredPaymentMethod' : preferredPaymentMethod,
},
headers: {
'Authorization': `Bearer AccessToken` //The token you obtained from the login API
}
)
.then(response => {
// post Response Contents
let singleInvoice = response.data.singleInvoice;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/invoice-api/invoices/single\
-H "content-type: application/json , Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-d "{
"customer": {
"name": "your customer name",
"email": "mail@domain.com",
"mobile": "01234567899"
},
"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",
"communicationLang": "en-gb",
"communicationMethod": "SMS",
"alertMerchantUponExpiry": "false",
"items": [
{
"itemCode": "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity": 2,
"price": 150.75,
"nameEn" : "description 1",
"nameAr" : "description 1",
"discount": {
"value": 20,
"type": "FLAT"
}
}
],
"paymentType": "PUSH_TO_CUSTOMER",
"taxes": 0,
"preferredPaymentMethod":"CARD"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/invoice-api/invoices/single");
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty ("Authorization","Bearer " + AccessToken); //The token you obtained from the login API
con.setDoOutput(true);
String jsonInputString = "{
"customer": {
"name": "your customer name",
"email": "mail@domain.com",
"mobile": "01234567899"
},
"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",
"communicationLang": "en-gb",
"communicationMethod": "SMS",
"alertMerchantUponExpiry": "false",
"items": [
{
"itemCode": "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity": 2,
"price": 150.75,
"nameEn" : "description 1",
"nameAr" : "description 1",
"discount": {
"value": 20,
"type": "FLAT"
}
}
],
"paymentType": "PUSH_TO_CUSTOMER",
"taxes": 0,
"preferredPaymentMethod":"CARD"
}";
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/single", new invoice_request
{
customer= {
name= "your customer name",
email= "mail@domain.com",
mobile= "01234567899"
},
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",
communicationLang= "en-gb",
communicationMethod= "SMS",
alertMerchantUponExpiry= "false",
items= [
{
itemCod= "b2f35ed2d39e462abd5e4b1129a7305d",
purchasedQuantit= 2,
pric= 150.75,
nameEn = "description 1",
"nameAr = "description 1",
discount= {
value= 20,
type= "FLAT"
}
}
],
paymentType= "PUSH_TO_CUSTOMER",
taxes= 0,
preferredPaymentMethod= "CARD" });
}
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[] customer { 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 string communicationLang { get; set; };
public string communicationMethod { 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:
{
"customer": {
"name": "your customer name",
"email": "mail@domain.com",
"mobile": "01234567899"
},
"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",
"communicationLang": "en-gb",
"communicationMethod": "SMS",
"alertMerchantUponExpiry": "false",
"items": [
{
"itemCode": "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity": 2,
"price": 150.75,
"nameEn" : "description 1",
"nameAr" : "وصف المنتج",
"discount": {
"value": 20,
"type": "FLAT"
}
}
],
"paymentType": "PUSH_TO_CUSTOMER",
"taxes": 0,
"preferredPaymentMethod":"CARD"
}
Response Parameters
FawryPay Sample Response
Whenever you call FawryPay Single Invoice API, you may expect a response in the form of JSON object which contains all adding single invoice processing information.
Sample Payment Single API Response
Response Parameters Description
| Parameter | type | Description | example |
|---|---|---|---|
| Invoice no. | String |
No. of the added invoice. | 4776211 |
Generating the Payment Link
After generating the Invoice number, you need to concatinate it with the pre-defined "base-URL" in your code, and this base URL is as below:
as mentioned above and after the concatination your payment should looks like below:
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. |
| 401 | Unauthorized (expired token). |
POSThttps://atfawry.fawrystaging.com/invoice-api/invoices/single
// 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.