3. Add Invoice

This endpoint is used to create a new invoice and obtain a payment URL. The payment URL can be sent to the customer to process the payment.

Endpoint

POST /api/addInvoice

Request Headers

HeaderRequiredDescription
AuthorizationYesBearer token provided by Authentication Endpoint
AcceptYesIt must be set to application/JSON.
Content-TypeYesIt must be set to application/JSON.
{
  "Authorization": "Bearer [id_token]",
  "Accept": "application/json",
  "Content-Type": "application/json"
}

Request Body Parameters

ParameterTypeRequiredDescription
orderNumberStringYesUnique number of the invoice in the merchant's system.
amountFloatYesThe total amount of the invoice. This amount is what the buyer will pay, regardless of the individual prices of the products.
callBackUrlStringYesThe URL that will be called when the payment is complete.
cancelUrlStringNoThe URL that will be called when the payment is canceled.
clientNameStringYesThe name of the client.
clientEmailStringNoThe email address of the client.
clientMobileStringYesThe mobile number of the client.
currencyStringNoThe currency code of the invoice. The default value is SAR. You can specify other currency codes like USD, EUR, or GBP.
productsArrayYesAn array of product objects to be included in the invoice. See Product Object Details.
smsMessageStringNoIf 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
supportedCardBrandsArrayNoList of supported card brands for payment.
Options include: [mada, visaMastercard, amex, tamara, stcpay, urpay]
displayPendingBooleanNoSetting this to true will display the invoice in my.paylink.sa
noteStringNoAny 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

ParameterTypeRequiredDescription
titleStringYesThe title of the product.
priceFloatYesThe price of the product.
qtyIntegerYesThe quantity of the product.
descriptionStringNoA description of the product.
isDigitalBooleanNoSet to true if the product is digital.
imageSrcStringNoA URL to an image of the product.
specificVatFloatNoThe VAT rate for the product. This will override the default VAT rate for the invoice if set.
productCostFloatNoThe cost of the product. This will be used to calculate the profit margin for the merchant.

- SMS Message Placeholders:

PlaceholderDescription
[CLIENT_NAME]Name of the client.
[TRANSACTION_NO]Transaction number from Paylink of the invoice.
[ORDER_NUMBER]The order number of the invoice.
[QR_URL]The URL that display QR code of the invoice.
[MOB_URL]The URL of the simple invoice format for mobile devices.
[SHORT_URL]The short URL of the invoice.
[AMOUNT]The amount of the invoice.
[WEB_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:

ParameterTypeDescription
gatewayOrderRequestObjectThe invoice details were sent to the gateway. See details below.
amountFloatThe total amount of the invoice.
transactionNoStringThe gateway assigns the transaction number.
orderStatusStringThe status of the invoice.
urlStringThe URL to the payment page.
qrUrlStringThe URL to the QR code image for the payment
mobileUrlStringTHE URL for mobile devices.
checkUrlStringThe 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.
digitalOrderBooleanThis field indicates whether the order contains digital products or not.
foreignCurrencyRateFloatThis is about the foreign currency rate used in the transaction, if applicable. In addition, it includes the exchange rate related to the SAR currency.
successBooleanThis 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.
paymentErrorsStringAny 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:

ParameterTypeDescription
detailStringA detailed error message explaining the reason for the failure.
titleStringA short title for the error that summarizes the reason for the failure.
typeStringA URL that identifies the type of error.
statusStringThe 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.