3. Add Invoices
Overview
This API documentation describes the addInvoice endpoint of the Paylink API, which allows merchants to generate invoices and receive payments online through the Paylink gateway. The merchant will send the payment URL to the customer through different channels or redirect them to the Paylink payment page.
Endpoint
POST /api/addInvoice
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token provided by Authentication Endpoint |
| Content-Type | Yes | It must be set to application/JSON. |
{
"Authorization": "Bearer [id_token]",
"accept": "application/json",
"content-type": "application/json"
}
Request Body Parameters
Creating an invoice requires information on the new invoice, such as the amount, callback URL, and client email. The following table describes the body parameters.
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | float | Yes | The total amount of the invoice. NOTE: Buyer will pay this amount regardless of the total amounts of the products' prices. |
| callBackUrl | string | No | The URL will be called when the payment is complete or canceled. |
| 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. (e.g., USD, EUR, GBP). |
| clientName | string | Yes | The name of the client. |
| note | string | No | A note for the invoice. |
| orderNumber | string | Yes | A unique identifier for the invoice. |
| products | array | Yes | An array of product objects will be included in the invoice. See product object details below. |
| smsMessage | string | No | This option will enable the invoice to be sent to the client's mobile specified in clientMobile. The message of this SMS can have placeholder for dynamic content. The placeholders are: - [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: The service requires additional aggrement with Paylink sales. |
| supportedCardBrands | Array | No | List of supported card brands. This list is optional. values are: [mada, visaMastercard, amex, tamara, stcpay, urpay] |
| displayPending | Boolean | No | This option will make this invoice displayed in my.paylink.sa |
Product Object Details
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | Yes | The title of the product. |
| price | float | Yes | The price of the product. |
| qty | int | Yes | The quantity of the product. |
| description | string | No | A description of the product. |
| isDigital | bool | 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. |
An example of the request is as follows:
{
"amount": 100.0,
"clientMobile": "0512345678",
"clientName": "Mohammed Ali",
"orderNumber": "123456789",
"products": [
{
"title": "Book",
"price": 50.0,
"qty": 2,
"description": null,
"isDigital": false,
"imageSrc": null,
"specificVat": null,
"productCost": null
}
],
"callBackUrl": "https://example.com",
"cancelUrl": "https://example.com",
"clientEmail": "[email protected]",
"currency": "SAR",
"note": "Test invoice",
"smsMessage": "URL: [SHORT_URL], Amount: [AMOUNT]",
"supportedCardBrands": ["mada", "visaMastercard", "amex", "tabby", "tamara", "stcpay", "urpay"],
"displayPending": true
}
Success Response
If the add invoice request success. The response details are as follows:
| 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. |
| paymentErrors | String | Any payment errors that occurred. |
| url | String | The URL to the payment page. |
| qrUrl | String | The URL to the QR code image for the payment |
| 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. |
| mobileUrl | String | THE URL for mobile devices. |
| 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. |
| 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. |
Example of the response:
{
"gatewayOrderRequest": {
"amount": 5.0,
"orderNumber": "MERCHANT-ANY-UNIQUE-ORDER-NUMBER-123123123",
"callBackUrl": "https://www.example.com",
"clientEmail": "[email protected]",
"clientName": "Zaid Matooq",
"clientMobile": "0509200900",
"note": "This invoice is for VIP client.",
"cancelUrl": null,
"products": [
{
"title": "Hand bag",
"price": 150.0,
"qty": 1,
"description": "Brown Hand bag leather for ladies",
"isDigital": true,
"imageSrc": "http://merchantwebsite.com/img/img1.jpg",
"specificVat": null,
"productCost": null
}
],
"supportedCardBrands": null,
"currency": null,
"smsMessage": null,
"displayPending": null,
"receivers": null,
"partnerPortion": null,
"metadata": null
},
"amount": 5.0,
"transactionNo": "1707943132122",
"orderStatus": "CREATED",
"paymentErrors": null,
"url": "https://paymentpilot.paylink.sa/pay/info/1707943132122",
"qrUrl": "https://restpilot.paylink.sa/openApi/loadOrderQRCode/1707943132122",
"mobileUrl": "https://paymentpilot.paylink.sa/pay/frame/1707943132122?n=Zaid%20Matooq&m=0509200900",
"checkUrl": "https://restpilot.paylink.sa/api/getInvoice/1707943132122",
"success": true,
"digitalOrder": true,
"foreignCurrencyRate": null,
"paymentReceipt": null,
"metadata": null
}
Failure Response:
If any failure occurred, the response details are as follows
| 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
Invoice minimum amount
The minimum invoice amount in the Paylink system is SAR 5.00.
Important use of GetInvoice in server side
Merchant's application must perform this endpoint on the server-side. Then send the resulting response to the client-side. If this endpoint is used in the client-side, then its result must be verified and confirmed using GetInvoice endpoint from the server-side to check the orderStatus equal to piad and the amount paid.
Try the endpoint
For more detail about the endpoint and to try it out, please click here.
Updated 14 days ago