SendPayment

Endpoint

Overview

The "SendPayment" endpoint is a POST request. It is used to create a MyFatoorah invoice. Detailed functionality of how to create an invoice is explained in the Invoice Link section.

The endpoint on Swagger is Payment_SendPayment.

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 the request header. The token of the 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.
CustomerName	string	Your customer name that will be displayed during the checkout.
NotificationOption	string	EML sends the invoice link by email only. You have to provide CustomerEmail. SMS sends the invoice link by SMS. You have to provide CustomerMobile. LNK returns the invoice link through the response body only ALL sends the invoice link by Email and SMS, also returns the invoice link through the response body.

Optional Fields

Input Parameter	Type	Description
MobileCountryCode	string, optional	Customer mobile number country code, for possible values please check here
CustomerMobile	string, optional Mandatory if the NotificationOption=SMS or ALL	It will be displayed on the invoice page. 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 Mandatory if the NotificationOption=EML or ALL	Customer email that will get the invoice URL
DisplayCurrencyIso	string, optional	The currency ISO code you want to display to the customer, by default it is the same as the base currency of the country API, for possible values please check here
CallBackUrl	string, optional	The return URL you like to have the 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. The localhost is not allowed to be set as a domain. The maximum number of characters is 254
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 that you can link with the invoice generated for reporting purposes
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. 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.
CustomerAddress	[CustomerAddressModel] (#customeraddressmodel) array, optional
ExpiryDate	string, optional	The date you want the invoice link 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 InvoiceSupplier objects, optional	This parameter is only mandatory if you are using the Multi-Vendors feature.

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

🚧

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

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

Consignee

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

InvoiceSupplier

Input Parameter	Type	Description
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.

---

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	number	The invoice number that you can use to inquire the invoice payment status later
InvoiceURL	string	The URL that should be sent to the customer to proceed with the payment, returned
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

---

Sample Messages

Request

{
  "CustomerName": "name",
  "NotificationOption": "ALL",
  "MobileCountryCode": "965",
  "CustomerMobile": "12345678",
  "CustomerEmail": "[email protected]",
  "InvoiceValue": 100,
  "DisplayCurrencyIso": "kwd",
  "CallBackUrl": "https://yoursite.com/success",
  "ErrorUrl": "https://yoursite.com/error",
  "Language": "en",
  "CustomerReference": "noshipping-nosupplier",
  "CustomerAddress": {
    "Block": "string",
    "Street": "string",
    "HouseBuildingNo": "string",
    "Address": "address",
    "AddressInstructions": "string"
  },
  "InvoiceItems": [
    {
      "ItemName": "string",
      "Quantity": 20,
      "UnitPrice": 5
    }
  ]
}

Response

{
    "IsSuccess": true,
    "Message": "Invoice Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 300034,
        "InvoiceURL": "https://demo.myfatoorah.com/ie/0106230003434",
        "CustomerReference": "noshipping-nosupplier",
        "UserDefinedField": null
    }
}