The "ExecutePayment" endpoint is a POST request. It is used to create a MyFatoorah invoice against a certain gateway. Detailed functionality of how to create an invoice is explained in the Gateway Integration section.

The endpoint on Swagger is: Payment_ExecutePayment.

Now, we are going to declare the endpoint and its models along with each accepted parameter and possible value.


Request Header

Add "Authorization": "Bearer {Token}" to request header. Token of demo configuration can be found here.

Request Model

The request is a POST request with the following parameters:

Required Fields

Input ParameterTypeDescription
InvoiceValuenumberThe amount you are seeking to charge the customer and accepts decimal value e.g. 2.500
PaymentMethodIdinteger, not required if SessionId providedFor example, it will be 2 for VISA/MASTER payment method
It is required if you did not pass a "SessionId"
SessionIdstring, not required if PaymentMethodId providedUsed according to the description in Embedded Payment


Only one of PaymentMethodId and SessionId is required.

Optional Fields

Input ParameterTypeDescription
CustomerName string, optionalYour customer name that should be displayed during the checkout
CallBackUrlstring, optionalThe return URL in case of a successful payment, refer to Payment Inquiry for more details.
The localhost is not allowed to be set as a domain.
ErrorUrlstring, optionalThe return URL in case of a failed payment or any exception raised during the payment, refer to Payment Inquiry for more details.
The localhost is not allowed to be set as a domain.
DisplayCurrencyIsostring, optionalThe currency ISO code you want to displayed to the customer, by default it is the same as the base currency of the country API, for possible values please click here
MobileCountryCodestring, optionalCustomer mobile number country code, for possible values please check here
CustomerMobile string, optionalString uses English letters ONLY and does not accept Arabic characters
Its length is between 0 and 11
Regular expression pattern is ^(?:(+)|(00)|(*)|())[0-9]{3,14}((#)|())$
CustomerEmail string, optionalCustomer email
Language string, optional"EN" to display the checkout page in English
"AR" to display the checkout page in Arabic
CustomerReferencestring, optionalRefers to the order or transaction ID in your own system and you can use for payment inquiry as well
CustomerCivilId string, optionalYour customer civil ID that you can associate with the transaction if needed
UserDefinedField string, optionalA custom field that you may use as additional information to be stored with the transaction.
The max length is 50 chars.
CustomerAdress CustomerAddressModel array, optional
ExpiryDate string, optionalThe date you want the payment to be expired, if not passed the default is considered from the account profile in the portal
InvoiceItemsArray of InvoiceItemModel objects, optional
ShippingMethodinteger, optional1 for DHL
2 for ARAMEX
ShippingConsigneeConsignee array, optionalThis parameter is only mandatory if you are creating a Shipping invoice.
SuppliersArray of InvoiceSuppliers objects, optionalThis parameter is only mandatory if you are using the Multi-Vendors feature.
RecurringModelRecurringModel object, optional


Input ParameterTypeDescription
Blockstring, optionalBlock number or area name that contains the delivery address
Streetstring, optionalDelivery address street name
HouseBuildingNostring, optionalHouse / Building number
Addressstring, optionalFull address details
AddressInstructionsstring, optionalAdditional instructions for the delivery address, landmark or directions


Input ParameterTypeDescription
ItemNamestringInvoice item name that will be displayed in the invoice
QuantityintegerItem quantity
UnitPricenumberItem unit price
Weightnumber, optional100 >= Weight > 0
Weight in kg
Widthnumber, optional200 >= Width > 0
Width in cm
Heightnumber, optional160 >= Height > 0
Height in cm
Depthnumber, optional200 >= Depth > 0
Depth in cm



In case you are using the InvoiceItemModel, the value sent in InvoiceValue should be equal to the total sum value of the item UnitPrice multiplied by the item Quantity, for example, if you are having 1 item with a price of 5 KD and quantity 3, so the value of the InvoiceValue should be 15


Input ParameterTypeDescription
EmailAddressstring, optional
PostalCodestring, optional


Input ParameterTypeType
SupplierCodeintegerThe supplier code you need to associate the invoice with, please refer to Multiple Suppliers feature.
ProposedSharenumber, optionalthe amount that the supplier will get after paying the invoice.
InvoiceSharenumberAmount specified for this supplier from the total invoice value.


Input ParameterTypeType
RecurringType string, optionalIt defines the interval time of charging the customer again with the same amount. Possible values are: Custom, Daily, Weekly, and Monthly.
IntervalDays integer, optionalIt is valid for the "custom" value of the RecurringType parameter. It is between 1 and 180 days.
Iteration integer, optionalIt determines how many times that you will charge the customer for your services.
RetryCountinteger, optional- It is an optional parameter.
- It accepts integer values only between '1' and '5'.
- It can be used in case of any failure recurring, to retry paying the same failed invoice till it paid or the count reset to zero.

Response Model

After viewing the Response Model that you will get as a result of your request, here, you will find full details about the Data Model of this API endpoint. Let's check it and its contents.

Response FieldTypeDescription
InvoiceId integerThe invoice number that you can use to inquire the invoice payment status later
IsDirectPayment boolean"true" or "false" to indicate if this URL for Direct Payment method
PaymentURL stringThe URL that you should redirect the customer to OR submit the card details to process the payment
CustomerReference stringRefers to the order or transaction ID in your system that you have sent in the request earlier
UserDefinedField stringThe custom field that you have passed in the request
RecurringId stringIf you set the RecurringModel array, the system will return the RecurringId value .


Returned Payment URL

The main value that will be returned from Execute Payment endpoint is PaymentURL which you will receive after the call, capture the response information to store it in your system and link it to your system order. Then you have to redirect your customer to this PaymentURL to proceed to the payment gateway OR if you are having Direct Payment enabled, this will be the endpoint that you have to submit the credit card information to

Sample Messages

   "CustomerName":"fname lname",
   "CustomerEmail":"[email protected]",
         "ItemName":"item name",
   "Message":"Invoice Created Successfully!",