Chargeback Notify WebHook API

NOTE

If the notifyurl parameter is passed, onlinepay will notify the address of the payment result

Overview

When a chargeback occurs for an order, the system will send a chargeback notification to the merchant's configured notification URL. Merchants need to implement receiving and verification logic according to this document.

Notification Method

Request Method: POST

Data Format: application/x-www-form-urlencoded

Character Encoding: UTF-8

Notification Parameters

Parameter	Type	Required	Description
tradeNo	String	Yes	Platform transaction order number
merOrderNo	String	Yes	Merchant order number
code	String	Yes	Notification type code
message	String	Yes	Notification message
reason	String	No	Chargeback reason description
currency	String	Yes	Chargeback amount currency
amount	String	Yes	Chargeback amount
sign	String	Yes	Signature value for verifying notification authenticity

Signature Verification

The system supports two signature methods: MD5 signature and RSA signature

MD5 Signature Verification

Signature Rules:

Concatenate strings in the following fixed order: tradeNo + merOrderNo + md5Key

Perform MD5 encryption on the concatenated string to get the signature value

RSA Signature Verification

Applicable Condition: Merchant encryption configuration is "1"

Signature Rules:

Sort all parameters (except sign) by parameter name in alphabetical order

Concatenate parameters in the format key1=value1&key2=value2

Use platform private key to perform SHA256withRSA signature on the concatenated string

Notification URL Configuration

The system will obtain notification URLs according to the following priority:

Priority 1: Merchant uploaded protest_notify_url during payment

Priority 2: Chargeback Notification URL configured in merchant backend developer center

If both URLs are not configured, no notification will be sent.

Response Requirements

After receiving the notification, merchants need to return HTTP status code 200 to indicate successful receipt. If other status codes are returned, the system will consider the notification failed.

Success Response Example:

HTTP/1.1 200 OK
Content-Type: text/plain

success

Security Recommendations

Must verify signature: Always verify the sign parameter after receiving notifications to ensure authenticity

Idempotency handling: The same chargeback may receive multiple notifications, merchants need to handle idempotency

Timely response: Recommend responding within 5 seconds to avoid timeout retries

Log recording: Recommend logging all received notifications and processing results for troubleshooting

Chargeback Notify WebHook API

Overview#

Notification Method#

Notification Parameters#

Signature Verification#

MD5 Signature Verification#

RSA Signature Verification#

Notification URL Configuration#

Response Requirements#

Security Recommendations#

Overview

Notification Method

Notification Parameters

Signature Verification

MD5 Signature Verification

RSA Signature Verification

Notification URL Configuration

Response Requirements

Security Recommendations