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
| 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: [mada, visaMastercard, amex, tamara, stcpay, urpay] |
| 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 |
|---|---|
| [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:
| 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.
Updated 2 months ago