Payin webhook

Callback notifications (Webhooks) allow your system to receive real-time updates about transaction status changes (e.g., when a user completes a payment).

1. Configuration Sources

The Callback URL (notify_url) can be configured in two ways. The system prioritizes the URL provided in the API request if both are present.

Merchant Dashboard (Static):

When onboarding, provide your default notify_url to the Lesspay Product Operations team to register it with your APPID.

This URL is used as a fallback if no URL is provided in the API request.

API Parameter (Dynamic):

You can specify a notify_url parameter in the Create Order API (/api/global/v1/pay/create-order).

This allows you to set different callback URLs for specific transactions or environments.

2. Webhook Authentication

To ensure that the webhook is sent by Lesspay and has not been tampered with, you must verify the signature included in the request header.

Signature Mechanism

Header Field: x-auth-signature

Algorithm: SHA256 (Uppercase)

Key: Your appSecret

Verification Steps

Collect Parameters: specific fields from the webhook JSON body (excluding empty values).

Sort: Sort the parameters by key in ASCII order.

Concatenate: Format them as key=value and join with & (e.g., amount=100&currency=USD).

Append Key: Append &key=YOUR_APP_SECRET to the string.

Hash: Calculate the SHA256 hash of the final string.

Compare: Convert the hash to Uppercase and compare it with the x-auth-signature header.

3. Notification Parameters

The webhook payload contains the following fields:

Field Name	Type	Location	Description
`request_id`	String	Body	Merchant's unique Request ID
`pay_order_id`	String	Body	Lesspay's unique Order ID
`order_status`	String	Body	Order status string (e.g., `SUCCEED`, `FAILED`)
`order_status_int`	Integer	Body	Order status (numeric)
`target_currency`	String	Body	Transaction Currency
`target_amount`	String	Body	Transaction Amount
`product_name`	String	Body	Product name
`description`	String	Body	Order description
`fail_url`	String	Body	Failure redirect URL
`success_url`	String	Body	Success redirect URL
`complete_time`	String	Body	Transaction completion time
`error_code`	String	Body	Error code (if failed)
`error_msg`	String	Body	Error message (if failed)
`api_version`	String	Body	API Version
`channel_biz_data`	Object	Body	Additional channel parameters

4. Examples

Data Format Example (POST JSON)

{
    "target_amount": "0.001",
    "target_currency": "ETH",
    "description": "Recharge_Order",
    "product_name": "Recharge_Order",
    "pay_order_id": "RO315733288037646399",
    "fail_url": "https://example.com/fail",
    "success_url": "https://example.com/success",
    "order_status_int": 0,
    "order_status": "SUCCEED",
    "request_id": "3233",
    "channel_biz_data": {
        "riskLevel": 3
    }
}

1. Configuration Sources#

2. Webhook Authentication#

Signature Mechanism#

Verification Steps#

3. Notification Parameters#

4. Examples#

Data Format Example (POST JSON)#

Callback Receiving Code Example (Java)#