Webhook
Payment and refund webhook notifications, signature verification, response rules, and retry policy
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.
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
| Webhook Type | Description | Trigger Condition |
|---|---|---|
| PAYMENT | Notifies the merchant of the payment result | Sent when a payment succeeds |
| REFUND | Notifies the merchant of the refund result | Sent when a refund succeeds or fails |
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": "USDT",
"billCurrency": "USDT",
"outerUid": "T3111...",
"txId": "PAYH20260105104613401...",
"rateExtra": 0,
"actionType": "ACQUIRER_PAY",
"billAmount": 0.99,
"orderAmount": 1,
"orderTime": 1767609970940,
"merchantId": 3000000...,
"cryptoAmount": 1,
"rate": 1,
"walletName": "redotpay",
"paymentMethod": "redotpay",
"paymentDeadline": 1767611755616,
"sn": "RA20260105104610940923...",
"paymentTime": 1767609973423,
"orderStatus": 2,
"coin": "USDT",
"clientIp": "13.230.109.247",
"source": "WEB",
"subMerchantCode": "STORE_A"
}| Field | Type | Required | Description |
|---|---|---|---|
outerOrder | String | Yes | Merchant’s original order number. DEPRECATED |
outerOrderSn | String | Yes | Merchant’s original order number |
preSn | String | Yes | Prepayment serial number, used to match previous requests. DEPRECATED |
orderSn | String | Yes | Prepayment serial number, used to match previous requests |
orderAmount | decimal | Yes | Order's original amount (up to merchant) |
orderCurrency | String | Yes | Order's original currency (up to merchant) |
cryptoAmount | decimal | Yes | Order's payment crypto currency amount |
cryptoCurrency | String | Yes | Order's payment crypto currency |
billAmount | decimal | Yes | Order's settlement amount |
billCurrency | String | Yes | Order's settlement currency |
fiatCurrency | String | Yes | Order's payment currency. DEPRECATED |
outerUid | String | Yes | External user ID or identifier passed when the payment was created |
txId | String | Yes | Channel payment transaction id |
rateExtra | decimal | Yes | Merchant exchange rate markup |
actionType | String | Yes | Type of payment webhook action. Always "ACQUIRER_PAY" for payment webhooks |
orderTime | long | Yes | Order creation time in milliseconds |
merchantId | long | Yes | Merchant's unique ID |
rate | String | Yes | Fiat to cryptocurrency exchange rates |
walletName | String | Yes | Payment selection wallet name. DEPRECATED |
paymentMethod | String | Yes | Payment selection wallet name |
paymentDeadline | long | Yes | Payment deadline in milliseconds. DEPRECATED |
timeExpire | long | Yes | Payment deadline in milliseconds |
sn | String | Yes | Payment serial number |
paymentTime | long | Yes | Successful payment completion time (timestamp in milliseconds) |
orderStatus | int | Yes | Payment status：1= Paying; 2= Success; 3= Payment failed; 4= Payment closed |
clientIp | String | Yes | Buyer's terminal ip |
source | String | Yes | buyer's source: H5/APP/WEB |
subMerchantCode | String | No | PSP sub-merchant business code from payment create. Present when tagged; otherwise null/empty. Not a separate merchant account. |
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",
"subMerchantCode": "STORE_A"
}Field Description
| Field | Type | Required | Description |
|---|---|---|---|
merchantRefundSn | String | Yes | Refund serial number sent by the merchant when initiating the refund |
refundSn | String | Yes | Refund reference number |
status | String | Yes | Refund result status: REFUNDING、SUCCESS、FAILED |
refundOrderAmount | decimal | Yes | Amount of refund order |
refundOrderCurrency | String | Yes | Currency of refund order |
failReason | String | No | Explains why refund order fails |
merchantId | long | Yes | Merchant's unique ID |
failReason | String | No | Reason the refund failed |
completeTime | long | Yes | Refund completion time (timestamp in milliseconds) |
outerOrderSn | String | Yes | Merchant’s original payment number related to the refund |
eventType | String | Yes | Type of refund webhook event "MERCHANT"= refund initiated by the merchant "PAY_DUPLICATION"= refund for duplicate payments; "PAY_EXPIRED" = refund for expired payments |
refundType | String | Yes | Refund channel types (Refund via original payment channel) |
refundAmount | decimal | Yes | Actual refund amount |
refundCurrency | String | Yes | Actual refund currency |
address | String | No | Refund wallet address (returned only for Web3 decentralized payments) |
subMerchantCode | String | No | PSP sub-merchant business code copied from the original payment. Not accepted on refund create; echoed here when the original order had it. |
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
| Field | Type | Required | Description |
|---|---|---|---|
code | String | Yes | "SUCCESS" or "FAIL" |
msg | String | No | Error message, present only when code is "FAIL" |
requestId | String | Yes | Unique request ID |
Retry Policy
| Condition | Retry Interval | Max Retries |
|---|---|---|
Non-SUCCESS code response | 180 seconds | 3 |
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.
Sandbox testing
Before you verify webhooks in sandbox, complete a test payment on the sandbox checkout. Sandbox QR codes cannot be scanned with the production RedotPay app.
Payment steps: Testing Payments in the Sandbox.