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 Parameter

Type

Description

InvoiceValue

number

The amount you are seeking to charge the customer and accepts decimal value 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.

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.

DisplayCurrencyIso

string, optional

The 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

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 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 max length is 50 chars.

CustomerAdress

CustomerAddressModel array, optional

ExpiryDate

string, optional

The date you want the payment to be expired, 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

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

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 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":""
   }
}


Did this page help you?