ExecutePayment

Endpoint

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 ParameterTypeDescription
InvoiceValuenumberThe amount you are seeking to charge the customer and accepts decimal values 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.
The maximum number of characters is 254
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.
The maximum number of characters is 254
DisplayCurrencyIsostring, optionalThe 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
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 it 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.
If in the beginning, you are using the save card characters, "CK-", the max length is 50 chars.
If you are using other characters, the maximum length is 500.
CustomerAdress CustomerAddressModel array, optional
ExpiryDate string, optionalThe date you want the payment to expire, 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
ProcessingDetailsProcessingDetails object, optional

CustomerAddressModel

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

InvoiceItemModel

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

🚧

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 ParameterTypeDescription
PersonNamestring
Mobilestring
EmailAddressstring, optional
LineAddressstring
CityNamestring
PostalCodestring, optional
CountryCodestring

InvoiceSuppliers

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

RecurringModel

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 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.

ProcessingDetails

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

Input ParameterTypeValue
AutoCaptureBooleantrue: To make the capture process directly without authorization
false: To make the authorization step first, then call UpdatePaymentStatus to capture/release the amount
Bypass3DSBooleantrue: 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 FieldTypeDescription
InvoiceIdintegerThe invoice number that you can use to inquire about the invoice payment status later
IsDirectPaymentboolean"true" or "false" to indicate if this URL for Direct Payment method
PaymentURLstringThe URL that you should redirect the customer to OR submit the card details to process the payment
CustomerReferencestringRefers to the order or transaction ID in your system that you have sent in the request earlier
UserDefinedFieldstringThe custom field that you have passed in the request
RecurringIdstringIf 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":""
   }
}