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 Recurring Invoice API
if you want to pay recurring invoice you can use Recurring 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 | |
|---|---|---|---|---|
| cycleType | String |
required | Values: "MONTH" or “WEEK”. | |
| cycleValue | integer |
required | Minimum 1. | |
| 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). | |
| discount
|
||||
| value | integer |
required | value of the discount. | |
| type | String |
required | values: “FLAT” or “PERCENTAGE”. | |
| 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. | |
| 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 Recurring Invoice API is given below.
function add_recurring_invoice(transaction_data) {
const recurringInvoice = {
cycleType: transaction_data.cycleType,
cycleValue: transaction_data.cycleValue,
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,
discount: transaction_data.discount,
items: transaction_data.items,
taxes: transaction_data.taxes,
preferredPaymentMethod: transaction_data.preferredPaymentMethod,
};
// Use fetch to send request data to FawryPay Recurring 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/recurring', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + transaction_data.token, // The token you obtained from the login API
},
body: JSON.stringify(recurringInvoice),
});
// Return and display the result of the charge.
return response.json();
}
$cycleType="MONTH";
$cycleValue=2;
$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";
$discount= [
"value"=> 20,
"type"=> "FLAT"
]
$items= [
"nameEn"=> "description 1",
"nameAr"=> "description 1",
"itemCode"=> "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity"=> 2,
"price"=> 150.75,
];
$taxes= 0;
$preferredPaymentMethod="CARD";
$response =request('POST', 'https://atfawry.fawrystaging.com/invoice-api/invoices/recurring', [
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer ' + $token, // The token you obtained from the login API
],
'body' => json_encode( [
'cycleType'=>$cycleType,
'cycleValue'=>$cycleValue,
'customer' => $customer,
'amount' => $amount,
'sendingDate' => $sendingDate,
'expiryDate' => $expiryDate,
'releaseDate' => $releaseDate,
'businessReference' => $businessReference,
'note' => $note,
'communicationLang' => $communicationLang,
'communicationMethod' => $communicationMethod,
'alertMerchantUponExpiry' => $alertMerchantUponExpiry,
'discount' => $discount,
'items' => $items,
'taxes' => $taxes,
'preferredPaymentMethod' => $preferredPaymentMethod,
] , true)
]);
$response = json_decode($response->getBody()->getContents(), true);
$recurringInvoice = $response['type']; // post response values
# importing the requests library
import requests
# importing Hash Library
import hashlib
# FawryPay add recurring invoice API Endpoint
URL = "https://atfawry.fawrystaging.com/invoice-api/invoices/recurring"
# invoice Data
cycleType='MONTH'
cycleValue=2
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'
discount= [
"value" : "20",
"type" : "FLAT"
]
items= [
"itemCode" : "b2f35ed2d39e462abd5e4b1129a7305d",
"purchasedQuantity" : 2,
"price" : 150.75,
"nameEn"=> "description 1",
"nameAr"=> "description 1",
]
taxes= 0
preferredPaymentMethod ='CARD'
# defining a params dict for the parameters to be sent to the API
recurringInvoice = {
'cycleType' : cycleType,
'cycleValue' : cycleValue,
'customer' : customer,
'amount' : amount,
'sendingDate' : sendingDate,
'expiryDate' : expiryDate,
'releaseDate' : releaseDate,
'businessReference' : businessReference,
'note' : note,
'communicationLang' : communicationLang,
'communicationMethod' : communicationMethod,
'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(recurringInvoice),
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_recurring_invoice() {
let cycleType= 'MONTH';
let cycleValue= 2;
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 discount= [
"value" : "20",
"type" : "FLAT"
]
let items= [
"nameEn" : "description 1",
"nameAr" : "description 1",
"price" : 150.75,
"discount" : [
"value" : "20",
"type" : "FLAT"
]
];
let taxes= 0;
let preferredPaymentMethod ='CARD';
axios.post('https://atfawry.fawrystaging.com/invoice-api/invoices/recurring', {
'cycleType' : cycleType,
'cycleValue' : cycleValue,
'customer' : customer,
'amount' : amount,
'sendingDate' : sendingDate,
'expiryDate' : expiryDate,
'releaseDate' : releaseDate,
'businessReference' : businessReference,
'note' : note,
'communicationLang' : communicationLang,
'communicationMethod' : communicationMethod,
'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 recurringInvoice = response.data.recurringInvoice;
//
})
.catch(error => {
console.log(error.response.data)
})
}
$ curl https://atfawry.fawrystaging.com/invoice-api/invoices/recurring\
-H "content-type: application/json , Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-d "{
"cycleType": "MONTH",
"cycleValue": 2,
"customer": {
"name": "samir ghoniem",
"email": "samir.ghoniem@fawry.com",
"mobile": "01234567899"
},
"sendingDate": "2021-02-27",
"expiryDate": "2021-03-17T20:52:06.000Z",
"businessReference": "123456",
"note": "invoice description",
"communicationLang": "en-gb",
"releaseDate": "2021-02-27T20:51:55.147Z",
"communicationMethod": "SMS",
"alertMerchantUponExpiry": "false",
"discount": {
"type": "PERCENTAGE",
"value": 10
},
"taxes": 0,
"amount": 250.5,
"items": [
{
"nameEn": "description 1",
"nameAr": "description 1",
"itemCode": "1cf4fc51ba984471ac3a063dfd7c6f4f",
"price": 250.5,
"purchasedQuantity": 1
}
],
"preferredPaymentMethod":"CARD"
}"
URL url = new URL ("https://atfawry.fawrystaging.com/invoice-api/invoices/recurring");
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 = "{
"cycleType": "MONTH",
"cycleValue": 2,
"customer": {
"name": "samir ghoniem",
"email": "samir.ghoniem@fawry.com",
"mobile": "01234567899"
},
"sendingDate": "2021-02-27",
"expiryDate": "2021-03-17T20:52:06.000Z",
"businessReference": "123456",
"note": "invoice description",
"communicationLang": "en-gb",
"releaseDate": "2021-02-27T20:51:55.147Z",
"communicationMethod": "SMS",
"alertMerchantUponExpiry": "false",
"discount": {
"type": "PERCENTAGE",
"value": 10
},
"taxes": 0,
"amount": 250.5,
"items": [
{
"nameEn": "description 1",
"nameAr": "description 1",
"itemCode": "1cf4fc51ba984471ac3a063dfd7c6f4f",
"price": 250.5,
"purchasedQuantity": 1
}
],
"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/recurring", new invoice_request
{
cycleType= "MONTH",
cycleValue= 2,
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",
discount= {
value= 20,
type= "FLAT"
},
items= [
{
itemCode= "b2f35ed2d39e462abd5e4b1129a7305d",
purchasedQuantity= 2,
price= 150.75,
nameEn= "description 1",
nameAr= "description 1",
}
],
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 cycleType { get; set; };
public double cycleValue { get; set; };
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[] discount { 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:
{
"cycleType": "MONTH",
"cycleValue": 2,
"customer": {
"name": "samir ghoniem",
"email": "samir.ghoniem@fawry.com",
"mobile": "01234567899"
},
"sendingDate": "2021-02-27",
"expiryDate": "2021-03-17T20:52:06.000Z",
"businessReference": "123456",
"note": "invoice description",
"communicationLang": "en-gb",
"releaseDate": "2021-02-27T20:51:55.147Z",
"communicationMethod": "SMS",
"alertMerchantUponExpiry": "false",
"discount": {
"type": "PERCENTAGE",
"value": 10
},
"taxes": 0,
"amount": 250.5,
"items": [
{
"nameEn": "description 1",
"nameAr": "description 1",
"itemCode": "1cf4fc51ba984471ac3a063dfd7c6f4f",
"price": 250.5,
"purchasedQuantity": 1
}
],
"preferredPaymentMethod":"CARD"
}
Response Parameters
FawryPay Sample Response
Whenever you call FawryPay Recurring Invoice API, you may expect a response in the form of JSON object which contains all pay recurring invoice processing information.
Sample Recurring Invoice 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/recurring
// 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.