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.