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/json; charset=UTF-8

Character Encoding: UTF-8

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.

What You Receive

POST your protest_notify_url
Content-Type: application/json

{
  "encryptedData": "U2FsdGVkX1+ghi789...=",
  "encryptedKey": "aZLW7pFrNgc+kJxsT2...=",
  "signType": "RSA256"
}

Step 1: Decrypt

// 1. RSA decrypt encryptedKey with OnlinePay Public Key → get AES key
// 2. AES decrypt encryptedData with AES key → get plaintext JSON below

Step 2: Decrypted Fields

Parameter	Type	Required	Description
tradeNo	String	Yes	Platform transaction order number
merOrderNo	String	Yes	Merchant order number
code	String	Yes	Notification type code, fixed value 11
message	String	Yes	Notification message
reason	String	No	Chargeback reason description
currency	String	Yes	Chargeback amount currency
amount	String	Yes	Chargeback amount
chargebackFee	String	Yes	Chargeback fee
chargebackCurrency	String	Yes	Chargeback currency
signType	String	Yes	`MD5` or `RSA256`
sign	String	Yes	Signature value for verifying notification authenticity

Decrypted JSON Example

{
  "tradeNo": "T202309011234567890",
  "merOrderNo": "MER20230901001",
  "code": "11",
  "message": "chargeback",
  "reason": "Unauthorized transaction",
  "currency": "USD",
  "amount": "100.00",
  "chargebackFee": "15.00",
  "chargebackCurrency": "USD",
  "signType": "RSA256",
  "sign": "d4e5f6g7h8..."
}

Step 3: Verify Signature

Sort all fields by key (exclude sign, signType, skip null/empty)

Join as key1=value1&key2=value2

Verify by signType:

MD5: MD5(signString + md5Key).toUpperCase() == sign

RSA256: RSA-SHA256-Verify(signString, sign, OnlinePay_PublicKey)

Example

Fields: tradeNo, merOrderNo, code, message, reason, currency, amount, chargebackFee, chargebackCurrency
Sign string: amount=100.00&chargebackCurrency=USD&chargebackFee=15.00&code=11&currency=USD&merOrderNo=MER20230901001&message=chargeback&reason=Unauthorized transaction&tradeNo=T202309011234567890

Step 4: Respond

Return HTTP 200 to acknowledge receipt. If other status codes are returned, the system will consider the notification failed.

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 URL Configuration

What You Receive

Step 1: Decrypt

Step 2: Decrypted Fields

Decrypted JSON Example

Step 3: Verify Signature

Example

Step 4: Respond

Security Recommendations

Request

Request Code Samples

Responses

Chargeback Notify WebHook API

Overview#

Notification Method#

Notification URL Configuration#

What You Receive#

Step 1: Decrypt#

Step 2: Decrypted Fields#

Decrypted JSON Example#

Step 3: Verify Signature#

Example#

Step 4: Respond#

Security Recommendations#

Request

Request Code Samples

Responses

Overview

Notification Method

Notification URL Configuration

What You Receive

Step 1: Decrypt

Step 2: Decrypted Fields

Decrypted JSON Example

Step 3: Verify Signature

Example

Step 4: Respond

Security Recommendations