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

ParameterTypeDescription
profileNoStringThe unique identifier of the partner profile

Headers

HeaderValueDescription
Content-Typeapplication/jsonThe MIME type of the request body
AuthorizationBearer {token}JWT token for authorization

Request Body

FieldTypeRequiredDescription
amountintegerYesThe total amount of the invoice
callBackUrlstringYesThe URL to which the system will send the callback after processing the invoice
clientMobilestringYesThe mobile number of the client
clientNamestringYesThe name of the client
notestringYesAdditional notes for the invoice
orderNumberstringYesThe order number associated with the invoice
productsarrayYesThe list of products in the invoice
├ descriptionstringYesThe description of the product
├ priceintegerYesThe price of the product
├ qtyintegerYesThe quantity of the product
â”” titlestringYesThe title of the product
partnerPortionobjectNoThe portion allocated to the partner
├ amountintegerNoThe amount allocated to the partner
â”” isPayingPaylinkFeesbooleanNoIndicates whether the partner is paying the Paylink fees
receiversarrayYesThe list of receivers for the invoice
├ keystringYesThe type of receiver (e.g., email)
├ valuestringYesThe receiver's identifier (e.g., email address)
├ amountintegerOptional for one receiver, Required for multiple receiversThe amount allocated to this receiver
├ notestringNoAdditional notes for this receiver
â”” isMainReceiverbooleanOptional for one receiver, Required for multiple receiversIndicates 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

FieldDescription
amountThe total amount of the invoice
callBackUrlThe URL to which the system will send the callback after processing the invoice
clientMobileThe mobile number of the client
clientNameThe name of the client
noteAdditional notes for the invoice
orderNumberThe order number associated with the invoice
productsThe list of products in the invoice
├ descriptionThe description of the product
├ priceThe price of the product
├ qtyThe quantity of the product
â”” titleThe title of the product
receiversThe list of receivers for the invoice
├ keyThe type of receiver (e.g., email)
├ valueThe receiver's identifier (e.g., email address)
├ amountThe amount allocated to this receiver (mandatory for multiple receivers)
â”” isMainReceiverIndicates if this receiver is the main receiver (mandatory for multiple receivers)

Optional Fields

FieldDescription
partnerPortionThe portion allocated to the partner
├ amountThe amount allocated to the partner
â”” isPayingPaylinkFeesIndicates whether the partner is paying the Paylink fees
receiversThe list of receivers for the invoice
├ amountThe amount allocated to this receiver (optional for one receiver)
â”” isMainReceiverIndicates 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.