Payment Callback Specification

Callback Request

Request Method

Method: POST

Content-Type: application/json

URL: notifyUrl configured by the merchant when creating the order

Request Headers

Content-Type: application/json

Request Body Format

The callback request body is in JSON format and contains order information and a signature field.

Callback Data Structure

Field Description

Common Fields

Field Name	Type	Required	Description
`type`	int64	Yes	Order type: 0 = Payin (Collection), 1 = Payout (Disbursement)
`merchantId`	int64	Yes	Merchant ID
`orderNo`	string	Yes	Merchant order number
`status`	int64	Yes	Order status (see status definitions)
`reason`	string	Yes	Reason description (English)
`payTime`	string	No	Payment time
`sign`	string	Yes	Signature (MD5, lowercase hexadecimal)

Amount Fields

All amount fields are numeric (decimal.Decimal). When serialized to JSON, values are numbers with two decimal places.

Field Name	Type	Required	Description
`orderAmount`	decimal.Decimal	Yes	Order amount
`paidAmount`	decimal.Decimal	No	Actual paid amount
`balanceAmount`	decimal.Decimal	No	Settlement amount (net amount credited to merchant)
`refundAmount`	decimal.Decimal	No	Refund amount
`fee`	decimal.Decimal	No	Transaction fee

Status Definitions

For details, see: Order Status

Amount Field Response Rules

Depending on order status and payment type, different amount fields are returned.

1. Failed / Timeout Status (status = 3 or 4)

✅ orderAmount

❌ No other amount fields

2. Payin Refund Status (type = 0, status = 6 or 7)

✅ orderAmount

✅ refundAmount

❌ No other amount fields

3. Payin Success Status (type = 0, status = 5)

✅ orderAmount

✅ paidAmount

✅ balanceAmount = paidAmount - fee

✅ fee

✅ payTime

4. Payout Success Status (type = 1, status = 2)

✅ orderAmount

✅ paidAmount

✅ balanceAmount = paidAmount + fee

✅ fee

✅ payTime

Signature Rules

Exclude sign field: The sign field itself is not included in signature calculation

Filter empty values: Exclude fields with empty values (null, empty string, 0, false)

Sort by key name: Sort all fields in lexicographical order by key

Build query string: Format key1=value1&key2=value2

Append secret key: Append &secret=YOUR_SECRET_KEY

Calculate MD5: Compute MD5 hash and output lowercase hexadecimal

Signature Calculation Example

Callback payload:

{
  "type": 0,
  "merchantId": 1001,
  "orderNo": "ORDER_123456",
  "orderAmount": 100.50,
  "paidAmount": 100.50,
  "balanceAmount": 98.50,
  "fee": 2.00,
  "status": 5,
  "reason": "Payment successful"
}

Secret Key: test_secret_key_12345_abcdefghijklmnop

Step 1: Exclude sign field

Step 2: Filter empty values

Step 3: Sort by key

balanceAmount=98.5
fee=2
merchantId=1001
orderAmount=100.5
orderNo=ORDER_123456
paidAmount=100.5
reason=Payment successful
status=5
type=0

Step 4: Build query string

balanceAmount=98.5&fee=2&merchantId=1001&orderAmount=100.5&orderNo=ORDER_123456&paidAmount=100.5&reason=Payment successful&status=5&type=0

Step 5: Append secret key

balanceAmount=98.5&fee=2&merchantId=1001&orderAmount=100.5&orderNo=ORDER_123456&paidAmount=100.5&reason=Payment successful&status=5&type=0&secret=test_secret_key_12345_abcdefghijklmnop

Step 6: Calculate MD5

987c6aa62092e2c6f5357da2da178d93

Signature Example Code

Go

FAQ

If signature verification fails, please ensure that numeric amount fields are serialized consistently and trailing zeros are not omitted incorrectly.

Payment Callback Specification

Payment Callback Specification#

Callback Request#

Request Method#

Request Headers#

Request Body Format#

Callback Data Structure#

Field Description#

Common Fields#

Amount Fields#

Status Definitions#

Amount Field Response Rules#

1. Failed / Timeout Status (status = 3 or 4)#

2. Payin Refund Status (type = 0, status = 6 or 7)#

3. Payin Success Status (type = 0, status = 5)#

4. Payout Success Status (type = 1, status = 2)#

Signature Rules#

Signature Calculation Example#

Signature Example Code#

Go#

FAQ#

Payment Callback Specification

Callback Request

Request Method

Request Headers

Request Body Format

Callback Data Structure

Field Description

Common Fields

Amount Fields

Status Definitions

Amount Field Response Rules

1. Failed / Timeout Status (status = 3 or 4)

2. Payin Refund Status (type = 0, status = 6 or 7)

3. Payin Success Status (type = 0, status = 5)

4. Payout Success Status (type = 1, status = 2)

Signature Rules

Signature Calculation Example

Signature Example Code

Go

FAQ