Webhook

1. Overview

When a payment succeeds or a refund is completed, whether it succeeds or fails,
RedotPay Connect's system will send a webhook to the merchant’s webhook URL.

Webhooks are sent separately for payment events and refund events.

If a webhook request fails (for example, due to a timeout or an error response), RedotPay Connect automatically retries it according to the retry policy.

NOTED: Webhooks also require signature verification.The signature will be passed by RedotPay Connect in the request header X-R-Signature during the webhooks.

2. Webhook Mechanism

⚠️

Each webhook is asynchronous and stateless.

Make sure your system handles it idempotently so retries do not cause duplicate processing.

Signature Verification

To ensure the authenticity and integrity of incoming webhook notifications and prevent forged requests, it is strongly recommended to verify the validity of the X-R-Signature header before processing any business logic.

The verification process involves extracting the signature, timestamp, and key version from the request headers, and validating them using your appKey and RedotPay's public key.

For the complete signature verification steps, code examples in multiple languages, and troubleshooting, please refer to the “Verifying RedotPay Callback Notification Signatures” section in the Request Signature and Verification Guide.

3. Payment Webhook

Request Example

{
    "outerOrder": "T300088...",
    "preSn": "RAP202601051045558385...",
    "orderCurrency": "USD",
    "billCoin": "USD",
    "outerUid": "T3111...",
    "txId": "PAYH20260105104613401...",
    "rateExtra": 0,
    "actionType": "ACQUIRER_PAY",
    "billAmount": 0.99,
    "orderAmount": 1,
    "orderTime": 1767609970940,
    "merchantId": 3000000...,
    "cryptoAmount": 1,
    "rate": 1,
    "walletName": "redotpay",
    "paymentDeadline": 1767611755616,
    "sn": "RA20260105104610940923...",
    "paymentTime": 1767609973423,
    "orderStatus": 2,
    "coin": "USDT",
    "clientIp": "13.230.109.247",
    "source": "WEB"
}

4. Refund Webhook

Request Example

{
    "refundSn": "RE2025121402253023...",
    "merchantRefundSn": "TestRefund20251201...",
    "merchantId": 2135213432...,
    "status": "SUCCESS",
    "completeTime": 1768357531591,
    "outerOrderSn": "test-quick-pay-1768301309...",
    "refundType": "redotpay",
    "createTime": 1768354530000,
    "refundAmount": 0.01001,
    "refundCurrency": "USDT",
    "eventType": "MERCHANT"
}

Field Description

5. Expected Merchant Response

After your system processes the webhook, your endpoint should return the following JSON response:

Response Example

{
    "code": "SUCCESS",
    "requestId": "0195c081-d54e-4569-a657-0f54388fa9ba"
}

{
    "code": "FAIL",
    "requestId": "0d992439-38a7-4674-9e06-19a7602eae2e",
    "msg":"update failed"
}

Response Rules

Retry Policy

The webhook is marked as failed after all retry attempts.
You can then use the query APIs to manually check the transaction or refund status.