Payment Callback Specification

Callback Request

Request Method

Method: POST

Content-Type: application/json

URL: notify_url 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)
`merchant_id`	int64	Yes	Merchant ID
`order_no`	string	Yes	Merchant order number
`status`	int64	Yes	Order status (see status definitions)
`reason`	string	Yes	Reason description (English)
`pay_time`	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
`order_amount`	decimal.Decimal	Yes	Order amount
`paid_amount`	decimal.Decimal	No	Actual paid amount
`balance_amount`	decimal.Decimal	No	Settlement amount (net amount credited to merchant)
`refund_amount`	decimal.Decimal	No	Refund amount
`fee`	decimal.Decimal	No	Transaction fee

Refund Fields

Field Name	Type	Required	Description
`merchant_refund_no`	string[]	No	All merchant refund numbers associated with this payin order, from refunds.

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)

✅ order_amount

❌ No other amount fields

2. Payin Refunding Status (type = 0, status = 9)

✅ order_amount

✅ merchant_refund_no

❌ paid_amount, balance_amount, fee, and pay_time are not included

3. Payin Refund Status (type = 0, status = 7 or 8)

✅ order_amount

✅ refund_amount

✅ merchant_refund_no

❌ paid_amount, balance_amount, fee, and pay_time are not included

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

✅ order_amount

✅ paid_amount

✅ balance_amount = paid_amount - fee

✅ fee

✅ pay_time

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

✅ order_amount

✅ paid_amount

✅ balance_amount = paid_amount + fee

✅ fee

✅ pay_time

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)

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

Array fields such as merchant_refund_no are included in the signature as their JSON string representation, for example ["refund_1","refund_2"].

Signature Calculation Example

Callback payload:

{
  "type": 0,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100.50,
  "paid_amount": 100.50,
  "balance_amount": 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

balance_amount=98.5
fee=2
merchant_id=1001
order_amount=100.5
order_no=ORDER_123456
paid_amount=100.5
reason=Payment successful
status=5
type=0

Step 4: Build query string

balance_amount=98.5&fee=2&merchant_id=1001&order_amount=100.5&order_no=ORDER_123456&paid_amount=100.5&reason=Payment successful&status=5&type=0

Step 5: Append secret key

balance_amount=98.5&fee=2&merchant_id=1001&order_amount=100.5&order_no=ORDER_123456&paid_amount=100.5&reason=Payment successful&status=5&type=0&secret=test_secret_key_12345_abcdefghijklmnop

Step 6: Calculate MD5

29fa2ad03349c534baafd36094e23c7f

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

Callback Request#

Request Method#

Request Headers#

Request Body Format#

Callback Data Structure#

Field Description#

Common Fields#

Amount Fields#

Refund Fields#

Status Definitions#

Amount Field Response Rules#

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

2. Payin Refunding Status (type = 0, status = 9)#

3. Payin Refund Status (type = 0, status = 7 or 8)#

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

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

Signature Rules#

Signature Calculation Example#

Signature Example Code#

Go#

FAQ#

Callback Request

Request Method

Request Headers

Request Body Format

Callback Data Structure

Field Description

Common Fields

Amount Fields

Refund Fields

Status Definitions

Amount Field Response Rules

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

2. Payin Refunding Status (type = 0, status = 9)

3. Payin Refund Status (type = 0, status = 7 or 8)

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

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

Signature Rules

Signature Calculation Example

Signature Example Code

Go

FAQ