Refund Notify WebHook API

NOTE

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

Overview

This document describes the interface specification for OnlinePay to send refund notifications to merchants, including parameter descriptions, signature verification methods, and other detailed information.

Interface Information

Request Method: POST

Content-Type: application/json; charset=UTF-8

Notification URL: Merchant configured refund notification URL

Success Indicator: Merchant returns HTTP 200

What You Receive

POST your notifyUrl
Content-Type: application/json

{
  "encryptedData": "U2FsdGVkX1+def456...=",
  "encryptedKey": "xHJK9sVtBqz+mNprY1...=",
  "signType": "MD5"
}

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

Basic Parameters

Parameter	Type	Required	Description
state	String	Yes	Refund status: 0-Success, 1-Failed
tradeNo	String	Yes	Platform transaction number
merOrderNo	String	Yes	Merchant order number
refundNo	String	Yes	Refund order number
message	String	No	Refund result description
refundAmount	String	Yes	Refund amount
refundCurrency	String	Yes	Refund currency
signType	String	Yes	`MD5` or `RSA256`
sign	String	Yes	Signature value

Decrypted JSON Example

{
  "state": "0",
  "tradeNo": "T202309011234567890",
  "merOrderNo": "MER20230901001",
  "refundNo": "R202309011234567890",
  "message": "Refund successful",
  "refundAmount": "100.00",
  "refundCurrency": "USD",
  "signType": "MD5",
  "sign": "abc123def456..."
}

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: state, tradeNo, merOrderNo, refundNo, message, refundAmount, refundCurrency
Sign string: merOrderNo=MER20230901001&message=Refund successful&refundAmount=100.00&refundCurrency=USD&refundNo=R202309011234567890&state=0&tradeNo=T202309011234567890

Step 4: Respond

Return HTTP 200 to acknowledge receipt.

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

success

Security Recommendations

Verify Signature: Always verify the signature of each notification to ensure the authenticity of the notification source

Idempotent Processing: Due to the retry mechanism, merchants should implement idempotent processing to avoid duplicate processing

HTTPS: It is recommended to use HTTPS protocol to receive notifications to ensure data transmission security

IP Whitelist: Configure IP whitelist to allow only specific IPs to send notifications

Refund Notify WebHook API

Overview

Interface Information

What You Receive

Step 1: Decrypt

Step 2: Decrypted Fields

Basic Parameters

Decrypted JSON Example

Step 3: Verify Signature

Example

Step 4: Respond

Security Recommendations

Request

Request Code Samples

Responses

Refund Notify WebHook API

Overview#

Interface Information#

What You Receive#

Step 1: Decrypt#

Step 2: Decrypted Fields#

Basic Parameters#

Decrypted JSON Example#

Step 3: Verify Signature#

Example#

Step 4: Respond#

Security Recommendations#

Request

Request Code Samples

Responses

Overview

Interface Information

What You Receive

Step 1: Decrypt

Step 2: Decrypted Fields

Basic Parameters

Decrypted JSON Example

Step 3: Verify Signature

Example

Step 4: Respond

Security Recommendations