ExecutePayment

Overview

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 Parameter	Type	Description
InvoiceValue	number	The amount you are seeking to charge the customer and accepts decimal values e.g. 2.500
PaymentMethodId	integer, not required if SessionId provided	For example, it will be 2 for VISA/MASTER payment method It is required if you did not pass a "SessionId"
SessionId	string, not required if PaymentMethodId provided	Used according to the description in Embedded Payment

❗️
Only one of PaymentMethodId and SessionId is required.

Optional Fields

Input Parameter	Type	Description
CustomerName	string, optional	Your customer name that should be displayed during the checkout
CallBackUrl	string, optional	The 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. The maximum number of characters is 254
ErrorUrl	string, optional	The 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. The maximum number of characters is 254
DisplayCurrencyIso	string, optional	The currency ISO code you want to display to the customer, by default is the same as the base currency of the country API, for possible values please click here
MobileCountryCode	string, optional	Customer mobile number country code, for possible values please check here
CustomerMobile	string, optional	String 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, optional	Customer email
Language	string, optional	"EN" to display the checkout page in English "AR" to display the checkout page in Arabic
CustomerReference	string, optional	Refers to the order or transaction ID in your own system and you can use it for payment inquiry as well
CustomerCivilId	string, optional	Your customer civil ID that you can associate with the transaction if needed
UserDefinedField	string, optional	A custom field that you may use as additional information to be stored with the transaction. The maximum length is 500.
CustomerAdress	CustomerAddressModel array, optional
ExpiryDate	string, optional	The date you want the payment to expire, if not passed the default is considered from the account profile in the portal
InvoiceItems	Array of InvoiceItemModel objects, optional
ShippingMethod	integer, optional	1 for DHL 2 for ARAMEX
ShippingConsignee	Consignee array, optional	This parameter is only mandatory if you are creating a Shipping invoice.
Suppliers	Array of InvoiceSuppliers objects, optional	This parameter is only mandatory if you are using the Multi-Vendors feature.
RecurringModel	RecurringModel object, optional
ProcessingDetails	ProcessingDetails object, optional
WebhookUrl	string, optional	You will get the webhook events for the created invoice on the specified Webhook URL. This includes transactions webhook, refunds webhook, capture/release webhook. The secret key for this URL will be the same as your webhook URL used in the dashboard. If you don't add this parameter, MyFatoorah sends the webhook event to the one configured in the dashboard.

CustomerAddressModel

Input Parameter	Type	Description
Block	string, optional	Block number or area name that contains the delivery address
Street	string, optional	Delivery address street name
HouseBuildingNo	string, optional	House / Building Number
Address	string, optional	Full address details
AddressInstructions	string, optional	Additional instructions for the delivery address, landmark or directions

InvoiceItemModel

Input Parameter	Type	Description
ItemName	string	Invoice item name that will be displayed in the invoice
Quantity	integer	Item Quantity
UnitPrice	number	Item unit price
Weight	number, optional	100 >= Weight > 0 Weight in kg
Width	number, optional	200 >= Width > 0 Width in cm
Height	number, optional	160 >= Height > 0 Height in cm
Depth	number, optional	200 >= Depth > 0 Depth in cm

🚧
Note
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

Consignee

Input Parameter	Type	Description
PersonName	string
Mobile	string
EmailAddress	string, optional
LineAddress	string
CityName	string
PostalCode	string, optional
CountryCode	string

InvoiceSuppliers

Input Parameter	Type	Type
SupplierCode	integer	The supplier code you need to associate the invoice with, please refer to Multiple Suppliers feature.
ProposedShare	number, optional	the amount that the supplier will get after paying the invoice.
InvoiceShare	number	Amount specified for this supplier from the total invoice value

RecurringModel

Input Parameter	Type	Type
RecurringType	string, optional	It defines the interval time of charging the customer again with the same amount. Possible values are Custom, Daily, Weekly, and Monthly.
IntervalDays	integer, optional	It is valid for the "custom" value of the RecurringType parameter. It is between 1 and 180 days.
Iteration	integer, optional	It determines how many times you will charge the customer for your services.
RetryCount	integer, 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.

ProcessingDetails

This parameter is used for payment methods that have the authorization and capture feature enabled.

Input Parameter	Type	Value
AutoCapture	Boolean	true: To make the capture process directly without authorization false: To make the authorization step first, then call UpdatePaymentStatus to capture/release the amount
Bypass3DS	Boolean	true: To bypass 3DS challenge false: To redirect the customer to the 3DS challenge The Bypass3DS feature must be enabled on your account to be able to use this feature.

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 Field	Type	Description
InvoiceId	integer	The invoice number that you can use to inquire about the invoice payment status later
IsDirectPayment	boolean	"true" or "false" to indicate if this URL for Direct Payment method
PaymentURL	string	The URL that you should redirect the customer to OR submit the card details to process the payment
CustomerReference	string	Refers to the order or transaction ID in your system that you have sent in the request earlier
UserDefinedField	string	The custom field that you have passed in the request
RecurringId	string	If 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

{
   "PaymentMethodId":1,
   "CustomerName":"fname lname",
   "DisplayCurrencyIso":"KWD",
   "MobileCountryCode":"965",
   "CustomerMobile":"12345678",
   "CustomerEmail":"[email protected]",
   "InvoiceValue":10,
   "CallBackUrl":"https://yoursite.com/success",
   "ErrorUrl":"https://yoursite.com/error",
   "Language":"ar",
   "CustomerReference":"noshipping-nosupplier",
   "CustomerAddress":{
      "Block":"string",
      "Street":"string",
      "HouseBuildingNo":"string",
      "AddressInstructions":"string"
   },
   "InvoiceItems":[
      {
         "ItemName":"item name",
         "Quantity":10,
         "UnitPrice":1,
         "Weight":2,
         "Width":3,
         "Height":4,
         "Depth":5
      }
   ]
}

{
   "IsSuccess":true,
   "Message":"Invoice Created Successfully!",
   "ValidationErrors":null,
   "Data":{
      "InvoiceId":927972,
      "IsDirectPayment":false,
      "PaymentURL":"https://demo.MyFatoorah.com/Ar/KWT/PayInvoice/Checkout?invoiceKey=0106292797237&paymentGatewayId=20",
      "CustomerReference":"noshipping-nosupplier",
      "UserDefinedField":null,
      "RecurringId":""
   }
}

ExecutePayment

Overview

📘
Request Header

Request Model

Required Fields

❗️

Optional Fields

CustomerAddressModel

InvoiceItemModel

🚧
Note

Consignee

InvoiceSuppliers

RecurringModel

ProcessingDetails

Response Model

👍
Returned Payment URL

Sample Messages

Overview

📘Request Header

Request Model

Required Fields

❗️

Optional Fields

CustomerAddressModel

InvoiceItemModel

🚧Note

Consignee

InvoiceSuppliers

RecurringModel

ProcessingDetails

Response Model

👍Returned Payment URL

Sample Messages

📘
Request Header

🚧
Note

👍
Returned Payment URL