3. Add Invoice

Endpoint

POST /api/addInvoice

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token provided by Authentication Endpoint
Accept	Yes	It must be set to application/JSON.
Content-Type	Yes	It must be set to application/JSON.

{
  "Authorization": "Bearer [id_token]",
  "Accept": "application/json",
  "Content-Type": "application/json"
}

Request Body Parameters

Parameter	Type	Required	Description
orderNumber	String	Yes	Unique number of the invoice in the merchant's system.
amount	Float	Yes	The total amount of the invoice. This amount is what the buyer will pay, regardless of the individual prices of the products.
callBackUrl	String	Yes	The URL that will be called when the payment is complete.
cancelUrl	String	No	The URL that will be called when the payment is canceled.
clientName	String	Yes	The name of the client.
clientEmail	String	No	The email address of the client.
clientMobile	String	Yes	The mobile number of the client.
currency	String	No	The currency code of the invoice. The default value is SAR. You can specify other currency codes like USD, EUR, or GBP.
products	Array	Yes	An array of product objects to be included in the invoice. See Product Object Details.
smsMessage	String	No	If provided, this message will be sent to the client's mobile number specified in clientMobile along with the invoice. It can contain dynamic placeholders for personalized content. See Placeholders List
supportedCardBrands	Array	No	List of supported card brands for payment. Options include*: \| Header \| Required \| Description
displayPending	Boolean	No	Setting this to true will display the invoice in my.paylink.sa
note	String	No	Any additional notes or comments related to the invoice.

📘
Invoice minimum amount
The minimum invoice amount in the Paylink system is SAR 5.00.

🚧
Required Parameters
Please ensure that all required parameters are included in your request body to avoid any errors.

- Product Object Details

Parameter	Type	Required	Description
title	String	Yes	The title of the product.
price	Float	Yes	The price of the product.
qty	Integer	Yes	The quantity of the product.
description	String	No	A description of the product.
isDigital	Boolean	No	Set to true if the product is digital.
imageSrc	String	No	A URL to an image of the product.
specificVat	Float	No	The VAT rate for the product. This will override the default VAT rate for the invoice if set.
productCost	Float	No	The cost of the product. This will be used to calculate the profit margin for the merchant.

- SMS Message Placeholders:

Placeholder	Description
LIENT_NAME]	Name of the client.
RANSACTION_NO]
RDER_NUMBER]	The order number of the invoice.
R_URL]	The URL that display QR code of the invoice.
OB_URL]	The URL of the simple invoice format for mobile devices.
HORT_URL]	The short URL of the invoice.
MOUNT]	The amount of the invoice.
EB_URL]	The full URL of the invoice. NOTE: This service requires additional agreement with Paylink sales.

An example of the request is as follows:

{
  "orderNumber": "123456789",
  "amount": 100,
  "callBackUrl": "https://example.com",
  "cancelUrl": "https://example.com",
  "clientName": "Mohammed Ali",
  "clientEmail": "[email protected]",
  "clientMobile": "0512345678",
  "currency": "SAR",
  "products": [
    {
      "title": "Book",
      "price": 50,
      "qty": 2,
      "description": "Book Description",
      "isDigital": false,
      "imageSrc": "https://example.com/book.png",
      "specificVat": 15,
      "productCost": 40
    }
  ],
  "smsMessage": "URL: [SHORT_URL], Amount: [AMOUNT]",
  "supportedCardBrands": [
    "mada",
    "visaMastercard",
    "amex",
    "tabby",
    "tamara",
    "stcpay",
    "urpay"
  ],
  "displayPending": true,
  "note": "Example invoice"
}

Success Response

If the request success, the response contains the following details:

Parameter	Type	Description
gatewayOrderRequest	Object	The invoice details were sent to the gateway. See details below.
amount	Float	The total amount of the invoice.
transactionNo	String	The gateway assigns the transaction number.
orderStatus	String	The status of the invoice.
url	String	The URL to the payment page.
qrUrl	String	The URL to the QR code image for the payment
mobileUrl	String	THE URL for mobile devices.
checkUrl	String	The URL of the API can be used to check the status of the price. NOTE: Calling this URL must have a token in the header.
digitalOrder	Boolean	This field indicates whether the order contains digital products or not.
foreignCurrencyRate	Float	This is about the foreign currency rate used in the transaction, if applicable. In addition, it includes the exchange rate related to the SAR currency.
success	Boolean	This field indicates whether this endpoint operation is successful or not. NOTE: This is not the payment or order status. It is the endpoint for getting invoice details.
paymentErrors	String	Any payment errors that occurred.

❗️
Invoice Lifetime
If the invoice status is not changed from "Pending" to "Paid" within 24 hours of creation, it will be automatically changed to "Canceled." Therefore, you will need to create a new invoice to use the payment service.

Example of the response:

{
  "gatewayOrderRequest": {
    "amount": 100.0,
    "orderNumber": "123456789",
    "callBackUrl": "https://example.com",
    "clientEmail": "[email protected]",
    "clientName": "Mohammed Ali",
    "clientMobile": "0512345678",
    "note": "Example invoice",
    "cancelUrl": "https://example.com",
    "products": [
      {
        "title": "Book",
        "price": 50.0,
        "qty": 2,
        "description": "Book Description",
        "isDigital": false,
        "imageSrc": "https://example.com/book.png",
        "specificVat": 15.0,
        "productCost": 40.0
      }
    ],
    "supportedCardBrands": [
      "mada",
      "visaMastercard",
      "amex",
      "tabby",
      "tamara",
      "stcpay",
      "urpay"
    ],
    "currency": "SAR",
    "smsMessage": "URL: [SHORT_URL], Amount: [AMOUNT]",
    "displayPending": true,
    "receivers": null,
    "partnerPortion": null,
    "metadata": null
  },
  "amount": 100.0,
  "transactionNo": "1716194603030",
  "orderStatus": "PENDING",
  "paymentErrors": null,
  "url": "https://payment.paylink.sa/pay/info/1716194603030",
  "qrUrl": "https://restapi.paylink.sa/openApi/loadOrderQRCode/1716194603030",
  "mobileUrl": "https://payment.paylink.sa/pay/frame/1716194603030?n=Mohammed%20Ali&m=0512345678",
  "checkUrl": "https://restapi.paylink.sa/api/getInvoice/1716194603030",
  "success": true,
  "digitalOrder": false,
  "foreignCurrencyRate": null,
  "paymentReceipt": null,
  "metadata": null
}

Failure Response:

If any failure occurred, the response details are as following:

Parameter	Type	Description
detail	String	A detailed error message explaining the reason for the failure.
title	String	A short title for the error that summarizes the reason for the failure.
type	String	A URL that identifies the type of error.
status	String	The HTTP status code for the response.

🚧
Important Note
The Merchant's application must execute this endpoint on the server-side and then forward the resulting response to the client-side.
If this endpoint is executed on the client-side, the response must be verified and confirmed using the Get Invoice endpoint from the server-side. This verification should check the actual orderStatus and paid amount.