Settlement Webhook

The webhook is triggered after each settlement by Paylink to the merchant. The webhook subscriber will receive a JSON object in the POST request body, following the above structure.

The WebHook object contains information about the settlement, including the settlement number, settlement bank, settlement amount, and settlement IBAN. It also includes a list of ReconciledOrder objects representing the orders in the settlement.

Each ReconciledOrder object contains details about an individual order, such as the order.

Register

Merchant has to register to this webhook service to use it. Call customer service to enable this service, or call your account manager to enable this service.

Request Type:

POST

Endpoint

Merchant has to set up the webhook in the https://my.paylink.sa portal. The setup is on the settings page, as appears in the following screenshot:

If any special authorization is needed for the Webhook request, the developer can set it in the headers fields—for example, Authorization: Bearer susdyfasdoifyaoifuasdfoisdufoisfdoicoivucoibucoibucoiuoiu.

Paylink will include it during the webhook call.

Request Body:

The request will contain the JSON object that includes all relevant information for the settlement. For example:

{
    "settlementNumber": "SETTLE123",
    "settlementBank": "AlRajhi",
    "settlementAmount": 1000.0,
    "settlementIban": "SA2342323423234234234234234",
    "reconciledOrders": [
        {
            "orderNumber": "ORDER123",
            "transactionNo": "TRANS456",
            "orderDate": "2023-06-12T15:30:00Z",
            "orderAmount": 500.0,
            "orderStatus": "COMPLETED",
            "paylinkFees": 10.0,
            "paylinkVat": 2.0,
            "note": "Example note",
            "clientName": "John Doe",
            "clientMobile": "+123456789",
            "isReconciled": true
        },
        {
            "orderNumber": "ORDER456",
            "transactionNo": "TRANS789",
            "orderDate": "2023-06-13T09:45:00Z",
            "orderAmount": 500.0,
            "orderStatus": "COMPLETED",
            "paylinkFees": 14.0,
            "paylinkVat": 2.8,
            "note": "",
            "clientName": "Jane Smith",
            "clientMobile": "+987654321",
            "isReconciled": true
        }
    ]
}

Response

The paylink system expects to receive 200 HTTP code responses to ensure the webhook reaches the merchant system. Otherwise, Paylink will try and keep sending the same webhook another ten times.

Suppose Paylink reaches ten times failure for the specific settlement webhook call. In that case, an email will be sent to the merchant's email notifying that the webhook call failed in that particular settlement.