Payment Webhook

Here's the updated documentation reflecting the additional fields in the JSON body sent in version 2:

Prerequisites

The merchant must be registered with Paylink to use this webhook service.

Request Type

Method: POST

Version Information

This documentation covers version 1 and version 2 of the Payment Webhook API. Merchants can select the desired version (v1 or v2) when setting up the webhook URL in the My Paylink Portal.

Partner Account Setup

If you are a partner managing multiple sub-merchants, setting the payment webhook in your partner account is sufficient to receive payment webhooks for all your sub-merchants. You do not need to configure the webhook individually for each sub-merchant account. This centralized setup ensures that you receive all payment notifications through a single webhook endpoint.

Endpoint Setup

Merchants must set up the webhook endpoint in the My Paylink Portal. This can be done on the settings page, where they can also select the API version (v1 or v2) they want to use, as shown in the following screenshot:

Headers

If any special header is required for the webhook request, the developer can include it in the header fields. For example:

{
  "Authorization": "Bearer [token]"
}

Paylink will include the authorization header in the webhook call.

Request Body

The webhook will send a JSON object containing all relevant information about the paid order. The structure of the JSON object differs between version 1 and version 2.

Version 1 Request Body

Parameter	Type	Description
amount	float	The total amount of the order.
merchantEmail	string	The email address of the merchant.
transactionNo	string	The transaction number generated by Paylink.
merchantOrderNumber	string	The merchant assigns the order number.
orderStatus	string	The status of the order (e.g., "Paid").

Example Request Body (Version 1):

{
  "amount": 150.0,
  "merchantEmail": "[email protected]",
  "transactionNo": "167845623412",
  "merchantOrderNumber": "ORD789012",
  "orderStatus": "Paid"
}

Version 2 Request Body

In version 2, the request body includes several additional fields to provide more comprehensive details about the transaction.

Parameter	Type	Description
amount	float	The total amount of the order.
merchantEmail	string	The email address of the merchant.
merchantMobile	string	The mobile number of the merchant.
merchantAccountNo	string	The account number of the merchant.
merchantLicenseType	string	The type of license the merchant holds.
merchantLicenseNo	string	The license number of the merchant.
transactionNo	string	The transaction number generated by Paylink.
merchantOrderNumber	string	The merchant assigns the order number.
orderStatus	string	The status of the order (e.g., "Paid").
paymentType	string	The payment method used for the order.
apiVersion	string	The API version being used (e.g., "v2").

Example Request Body (Version 2):

{
  "amount": 150.0,
  "merchantEmail": "[email protected]",
  "merchantMobile": "966555123456",
  "merchantAccountNo": "ACC123456789",
  "merchantLicenseType": "Commercial",
  "merchantLicenseNo": "LIC987654321",
  "transactionNo": "167845623412",
  "merchantOrderNumber": "ORD789012",
  "orderStatus": "Paid",
  "paymentType": "mada",
  "apiVersion": "v2"
}

Supported `paymentType` Values

The paymentType field in version 2 can have the following values:

`paymentType` Value	Description
`mada`	Mada card
`visaMastercard`	Visa or MasterCard
`stcpay`	STC Pay
`tabby`	Tabby
`tamara`	Tamara
`urpay`	UrPay
`a2a`	Account-to-Account transfer (ANB)
`amex`	American Express (Amex)
`sadad`	Sadad payment

Expected Response

HTTP Status Code: 200

The merchant's system is expected to respond with a 200 HTTP status code to acknowledge the receipt of the webhook.

Error Handling

If the webhook is not acknowledged with a 200 HTTP status code, Paylink will retry sending the webhook up to ten times at intervals.