Guides

SendPayment

Endpoint

Suggest Edits

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 ParameterTypeDescription
InvoiceValuenumberThe amount you are seeking to charge the customer and accepts decimal values e.g. 2.500.
CustomerNamestringYour customer name that will be displayed during the checkout.
NotificationOptionstringEML 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 ParameterTypeDescription
MobileCountryCodestring, optionalCustomer mobile number country code, for possible values please check here
CustomerMobilestring, 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}((#)|())$
CustomerEmailstring, optional
Mandatory if the NotificationOption=EML or ALL		Customer email that will get the invoice URL
DisplayCurrencyIsostring, optionalThe 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
CallBackUrlstring, optionalThe 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
ErrorUrlstring, optionalThe 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
Languagestring, optionalEN 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 that you can link with the invoice generated for reporting purposes
CustomerCivilIdstring, optionalYour customer civil ID that you can associate with the transaction if needed
UserDefinedFieldstring, 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.
CustomerAddress [CustomerAddressModel] (#customeraddressmodel) array, optional
ExpiryDatestring, optionalThe date you want the invoice link 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 InvoiceSupplier objects, optionalThis parameter is only mandatory if you are using the Multi-Vendors feature.
WebhookUrlstring, optionalYou 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.
InvoicePaymentMethodsArrayEnter the PaymentMethodId for the payment methods you want to display on the invoice. You can find the PaymentMethodId for each payment method from InitiatePayment endpoint.

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

🚧

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

Consignee

Input ParameterTypeDescription
PersonNamestring
Mobilestring
EmailAddressstring, optional
LineAddressstring
CityNamestring
PostalCodestring, optional
CountryCodestring

InvoiceSupplier

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

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

Sample Messages

{
  "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
    }
  ]
}

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

Updated 4 days ago