Create a Sub-Merchant Invoice
The Add Merchant Invoice API endpoint allows partners to create a new invoice for a specified merchant profile. This API requires an authenticated request with a JWT token and accepts JSON data (use this endpoint to get token). The mandatory fields include the total invoice amount, callback URL, client mobile number, client name, invoice notes, order number, product details, and receiver information. For invoices with multiple receivers, the main receiver must be specified. An optional partnerPortion
field can be included to allocate a specific amount to the partner and indicate whether they are paying Paylink fees. If the partnerPortion
is not specified, the system will retrieve the values from the original relationship between the merchant and partner. This endpoint is available in production and testing environments, ensuring a seamless integration process for managing merchant invoices efficiently.
API Documentation for Adding a Merchant Invoice
Endpoint
POST /rest/partner/addMerchantInvoice/{profileNo}
Description
This endpoint allows partners to add a new merchant invoice.
Request URLs
- Production URL:
https://order.paylink.sa/rest/partner/addMerchantInvoice/{profileNo}
- Testing URL:
https://orderpilot.paylink.sa/rest/partner/addMerchantInvoice/{profileNo}
Path Parameters
Parameter | Type | Description |
---|---|---|
profileNo | String | The unique identifier of the partner profile |
Headers
Header | Value | Description |
---|---|---|
Content-Type | application/json | The MIME type of the request body |
Authorization | Bearer {token} | JWT token for authorization |
Request Body
Field | Type | Required | Description |
---|---|---|---|
amount | integer | Yes | The total amount of the invoice |
callBackUrl | string | Yes | The URL to which the system will send the callback after processing the invoice |
clientMobile | string | Yes | The mobile number of the client |
clientName | string | Yes | The name of the client |
note | string | Yes | Additional notes for the invoice |
orderNumber | string | Yes | The order number associated with the invoice |
products | array | Yes | The list of products in the invoice |
├ description | string | Yes | The description of the product |
├ price | integer | Yes | The price of the product |
├ qty | integer | Yes | The quantity of the product |
â”” title | string | Yes | The title of the product |
partnerPortion | object | No | The portion allocated to the partner |
├ amount | integer | No | The amount allocated to the partner |
â”” isPayingPaylinkFees | boolean | No | Indicates whether the partner is paying the Paylink fees |
receivers | array | Yes | The list of receivers for the invoice |
├ key | string | Yes | The type of receiver (e.g., email) |
├ value | string | Yes | The receiver's identifier (e.g., email address) |
├ amount | integer | Optional for one receiver, Required for multiple receivers | The amount allocated to this receiver |
├ note | string | No | Additional notes for this receiver |
â”” isMainReceiver | boolean | Optional for one receiver, Required for multiple receivers | Indicates if this receiver is the main receiver (default is false) |
Request Body Examples
For One Receiver
{
"amount": 125,
"callBackUrl": "https://example.com/store",
"clientMobile": "0569026000",
"clientName": "Zaid Matooo",
"note": "This invoice is for VIP client.",
"orderNumber": "ORDER_123123123",
"products": [
{
"description": "Woman Bag Black",
"price": 150,
"qty": 1,
"title": "Woman Bag"
}
],
"receivers": [
{
"key": "email",
"value": "[email protected]"
}
]
}
For Multiple Receivers
{
"amount": 150,
"callBackUrl": "https://example.com/store",
"clientMobile": "0569026000",
"clientName": "Zaid Matooo",
"note": "This invoice is for VIP client.",
"orderNumber": "ORDER_123123123",
"products": [
{
"description": "Woman Bag Black",
"price": 150,
"qty": 1,
"title": "Woman Bag"
}
],
"partnerPortion": {
"amount": 50,
"isPayingPaylinkFees": true
},
"receivers": [
{
"key": "email",
"value": "[email protected]",
"amount": 50,
"note": "This invoice is for VIP client.",
"isMainReceiver": true
},
{
"key": "email",
"value": "[email protected]",
"amount": 25,
"note": "This invoice is for VIP client."
}
]
}
Mandatory Fields
Field | Description |
---|---|
amount | The total amount of the invoice |
callBackUrl | The URL to which the system will send the callback after processing the invoice |
clientMobile | The mobile number of the client |
clientName | The name of the client |
note | Additional notes for the invoice |
orderNumber | The order number associated with the invoice |
products | The list of products in the invoice |
├ description | The description of the product |
├ price | The price of the product |
├ qty | The quantity of the product |
â”” title | The title of the product |
receivers | The list of receivers for the invoice |
├ key | The type of receiver (e.g., email) |
├ value | The receiver's identifier (e.g., email address) |
├ amount | The amount allocated to this receiver (mandatory for multiple receivers) |
â”” isMainReceiver | Indicates if this receiver is the main receiver (mandatory for multiple receivers) |
Optional Fields
Field | Description |
---|---|
partnerPortion | The portion allocated to the partner |
├ amount | The amount allocated to the partner |
â”” isPayingPaylinkFees | Indicates whether the partner is paying the Paylink fees |
receivers | The list of receivers for the invoice |
├ amount | The amount allocated to this receiver (optional for one receiver) |
â”” isMainReceiver | Indicates if this receiver is the main receiver (optional for one receiver) |
Response
Success
- Status Code:
200 OK
- Body: JSON object with details of the created invoice.
Error
- Status Code:
400 Bad Request
- Returned if the request body is malformed or missing required fields.
- Status Code:
401 Unauthorized
- Returned if the provided token is invalid or expired.
- Status Code:
500 Internal Server Error
- Returned if there is an error on the server side while processing the request.
Example Requests
For One Receiver
curl --location 'https://order.paylink.sa/rest/partner/addMerchantInvoice/33588201' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJoYXNzYW4uYXlvdWIuMTk4MEBnbWFpbC5jb20iLCJhdXRoIjoiUk9MRV9NRVJDSEFOVCxST0xFX01FUkNIQU5UX0FDQ09VTlQsUk9MRV9QQVJUTkVSIiwiaXNzIjoiQVBJIiwiZXhwIjoxNzI0MDQ3MDE2fQ.L328KzUvD3nkPNzSnrbiSBQhn1kKUZGfgEzL8GuEzwzGocrSpI2IE2Y4gv0-aLDYg2Ya7o_srwWhz68wqzITpQ' \
--data-raw '{
"amount": 125,
"callBackUrl": "https://example.com/store",
"clientMobile": "0569026000",
"clientName": "Zaid Matooo",
"note": "This invoice is for VIP client.",
"orderNumber": "ORDER_123123123",
"products": [
{
"description": "Woman Bag Black",
"price": 150,
"qty": 1,
"title": "Woman Bag"
}
],
"receivers": [
{
"key": "email",
"value": "[email protected]"
}
]
}'
For Multiple Receivers (complete fields)
curl --location 'https://order.paylink.sa/rest/partner/addMerchantInvoice/33588201' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJoYXNzYW4uYXlvdWIuMTk4MEBnbWFpbC5jb20iLCJhdXRoIjoiUk9MRV9NRVJDSEFOVCxST0xFX01FUkNIQU5UX0FDQ09VTlQsUk
9MRV9QQVJUTkVSIiwiaXNzIjoiQVBJIiwiZXhwIjoxNzI0MDQ3MDE2fQ.L328KzUvD3nkPNzSnrbiSBQhn1kKUZGfgEzL8GuEzwzGocrSpI2IE2Y4gv0-aLDYg2Ya7o_srwWhz68wqzITpQ' \
--data-raw '{
"amount": 150,
"callBackUrl": "https://example.com/store",
"clientMobile": "0569026000",
"clientName": "Zaid Matooo",
"note": "This invoice is for VIP client.",
"orderNumber": "ORDER_123123123",
"products": [
{
"description": "Woman Bag Black",
"price": 150,
"qty": 1,
"title": "Woman Bag"
}
],
"partnerPortion": {
"amount": 50,
"isPayingPaylinkFees": true
},
"receivers": [
{
"key": "email",
"value": "[email protected]",
"amount": 50,
"note": "This invoice is for VIP client.",
"isMainReceiver": true
},
{
"key": "email",
"value": "[email protected]",
"amount": 25,
"note": "This invoice is for VIP client."
}
]
}'
For Multiple Receivers (without specifying a partner)
curl --location 'https://order.paylink.sa/rest/partner/addMerchantInvoice/33588201' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJoYXNzYW4uYXlvdWIuMTk4MEBnbWFpbC5jb20iLCJhdXRoIjoiUk9MRV9NRVJDSEFOVCxST0xFX01FUkNIQU5UX0FDQ09VTlQsUk
9MRV9QQVJUTkVSIiwiaXNzIjoiQVBJIiwiZXhwIjoxNzI0MDQ3MDE2fQ.L328KzUvD3nkPNzSnrbiSBQhn1kKUZGfgEzL8GuEzwzGocrSpI2IE2Y4gv0-aLDYg2Ya7o_srwWhz68wqzITpQ' \
--data-raw '{
"amount": 150,
"callBackUrl": "https://example.com/store",
"clientMobile": "0569026000",
"clientName": "Zaid Matooo",
"note": "This invoice is for VIP client.",
"orderNumber": "ORDER_123123123",
"products": [
{
"description": "Woman Bag Black",
"price": 150,
"qty": 1,
"title": "Woman Bag"
}
],
"receivers": [
{
"key": "email",
"value": "[email protected]",
"amount": 50,
"note": "This invoice is for VIP client.",
"isMainReceiver": true
},
{
"key": "email",
"value": "[email protected]",
"amount": 25,
"note": "This invoice is for VIP client."
}
]
}'
This documentation provides a comprehensive guide on using the API to add a new merchant invoice, including detailed information on the endpoint, headers, request body, and expected responses.
Updated 5 months ago