Payout API Development Documentation

This document describes the payout platform Open API and helps merchants integrate payout order creation, order query, and balance query services.

1. Table of Contents

1.1. Create Payout Order

1.2. Query Payout Order

1.3. Query Payout Balance

2. Interface Description

2.1 Basic Information

2.1.1 Request Format

All interfaces use the POST method and the request body format is application/json.

2.1.2 Common Request Parameters

Parameter	Type	Required	Description	Notes
mchNo	string	Yes	Merchant number	Assigned by the platform. It is recommended to use the merchant API key/account identifier.
reqTime	int64	Yes	Request timestamp	13-digit millisecond timestamp
sign	string	Yes	Request signature	See Signature Algorithm

2.1.3 Response Format

All interfaces use the following unified response format:

Parameter	Type	Description
code	int32	Status code. 0 means success; other values mean failure.
msg	string	Response message
sign	string	Response signature. It may be empty in some failure scenarios.
data	object	Response data. See each API section for details.

2.1.4 Signature Description

To ensure request parameters are not tampered with, the platform uses MD5 digest signature authentication for Open API requests.

For complete signing rules, examples, and code samples, see Signature Algorithm.

Notes:

1. The sign field itself does not participate in signing.
2. Parameter names are case-sensitive and must match the API field names.
3. Amount fields are transferred as integers according to the platform unit. Do not pass decimals.
4. reqTime must be a 13-digit millisecond timestamp.

2.1.5 Amount Unit

Payout amount fields are transferred as integers. The unit is 0.0001 CNY, which means the real amount multiplied by 10000.

Real Amount	API amount
0.5 CNY	5000
1 CNY	10000
100 CNY	1000000

3. API Details

3.1 Create Payout Order

3.1.1 Scenario

The merchant submits a payout order. After the platform accepts it, the platform payout order ID and order state are returned. The merchant order number must be unique. Duplicate submissions return an existing-order error.

3.1.2 Endpoint

Item	Content
URL	/api/v1/payout/order
Method	POST

Body Parameters

{
  "mchNo": "10001",
  "mchOrderNo": "PO202406010001",
  "amount": 1000000,
  "accountName": "Zhang San",
  "accountNo": "6222020202020202020",
  "bankName": "ICBC",
  "bankBranch": "Shanghai Branch",
  "notifyUrl": "https://merchant.example.com/notify/payout",
  "payCode": "BANK",
  "remark": "Payout test order",
  "reqTime": 1717651200000,
  "sign": "MD5_UPPER_SIGN"
}

Field	Type	Required	Description
mchNo	string	Yes	Merchant number
mchOrderNo	string	Yes	Merchant payout order number. It must be unique on the merchant side.
amount	int64	Yes	Payout amount. Unit: 0.0001 CNY
accountName	string	Yes	Payee name
accountNo	string	Yes	Payee account/card number
bankName	string	Yes	Bank or institution name
bankBranch	string	Yes	Branch or institution note
notifyUrl	string	Yes	Asynchronous notification URL. If notification is not required, pass NOURL. Empty strings are not recommended.
payCode	string	Yes	Payout channel code
remark	string	No	Merchant remark, retained for reconciliation
reqTime	int64	Yes	13-digit millisecond timestamp
sign	string	Yes	Uppercase MD5 signature

3.1.3 Return Codes

code	Description
0	Accepted successfully
200026	Signature verification failed
Other	Business failure. See msg for details.

3.1.4 Response Example

Success

{
  "code": 0,
  "msg": "success",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "payoutOrderId": "PO20240601000001",
    "mchOrderNo": "PO202406010001",
    "amount": 1000000,
    "state": 1,
    "createdAt": 1717651200000
  }
}

Failure

{
  "code": 200026,
  "msg": "Signature verification failed"
}

Data Fields

Field	Type	Description
payoutOrderId	string	Platform payout order ID
mchOrderNo	string	Merchant payout order number
amount	int64	Payout amount. Unit: 0.0001 CNY
state	int32	Order state. See Order State.
createdAt	int64	Creation time, 13-digit millisecond timestamp

---

3.2 Query Payout Order

3.2.1 Scenario

The merchant can query the payout order state by merchant payout order number or platform payout order ID.

3.2.2 Endpoint

Item	Content
URL	/api/v1/payout/query
Method	POST

Body Parameters

{
  "mchNo": "10001",
  "mchOrderNo": "PO202406010001",
  "payoutOrderId": "PO20240601000001",
  "reqTime": 1717651200000,
  "sign": "MD5_UPPER_SIGN"
}

Field	Type	Required	Description
mchNo	string	Yes	Merchant number
mchOrderNo	string	No	Merchant payout order number. Choose one between mchOrderNo and payoutOrderId.
payoutOrderId	string	No	Platform payout order ID. Choose one between payoutOrderId and mchOrderNo.
reqTime	int64	Yes	13-digit millisecond timestamp
sign	string	Yes	Uppercase MD5 signature

3.2.3 Return Codes

code	Description
0	Query successful
200026	Signature verification failed
Other	Business failure. See msg for details.

3.2.4 Response Example

Success

{
  "code": 0,
  "msg": "success",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "payoutOrderId": "PO20240601000001",
    "mchOrderNo": "PO202406010001",
    "amount": 1000000,
    "state": 3,
    "successTime": 1717651800000,
    "remark": ""
  }
}

Failure

{
  "code": 404,
  "msg": "Order not found"
}

Data Fields

Field	Type	Description
payoutOrderId	string	Platform payout order ID
mchOrderNo	string	Merchant payout order number
amount	int64	Payout amount. Unit: 0.0001 CNY
state	int32	Order state. See Order State.
successTime	int64	Success time, 13-digit millisecond timestamp
remark	string	Failure reason or remark

---

3.3 Query Payout Balance

3.3.1 Scenario

The merchant queries current available balance and frozen balance.

3.3.2 Endpoint

Item	Content
URL	/api/v1/payout/balance
Method	POST

Body Parameters

{
  "mchNo": "10001",
  "reqTime": 1717651200000,
  "sign": "MD5_UPPER_SIGN"
}

Field	Type	Required	Description
mchNo	string	Yes	Merchant number
reqTime	int64	Yes	13-digit millisecond timestamp
sign	string	Yes	Uppercase MD5 signature

3.3.3 Return Codes

code	Description
0	Query successful
200026	Signature verification failed
Other	Business failure. See msg for details.

3.3.4 Response Example

Success

{
  "code": 0,
  "msg": "success",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "mchNo": "10001",
    "mchName": "Test Merchant",
    "balance": 10000000,
    "frozenBalance": 500000
  }
}

Data Fields

Field	Type	Description
mchNo	string	Merchant number
mchName	string	Merchant name
balance	int64	Available balance. Unit: 0.0001 CNY
frozenBalance	int64	Frozen balance. Unit: 0.0001 CNY

---

4. Asynchronous Notification

4.1 Notification Description

When a payout order reaches a final state, the platform pushes an asynchronous notification to the notifyUrl submitted by the merchant. If notifyUrl is NOURL, no notification is pushed for that order.

4.2 Request Method

Item	Content
Method	POST
Content-Type	application/json
Encoding	UTF-8
Notification URL	The notifyUrl submitted when creating the payout order

4.3 Notification Parameters

The platform sends the notification body in JSON format:

Field	Type	Required	Description
platform_order_no	string	Yes	Platform payout order ID
merchant_order_no	string	Yes	Merchant payout order number
merchant_id	int64	Yes	Platform merchant ID
amount	int64	Yes	Order amount. Unit: 0.0001 CNY
actual_amount	int64	Yes	Actual payout amount. Unit: 0.0001 CNY
success_amount	int64	Yes	Successful payout amount. Unit: 0.0001 CNY
status	int32	Yes	Order state. See Order State.
fail_reason	string	Yes	Failure reason. Usually empty when successful.
currency	string	Yes	Currency, for example RMB

After successfully processing the notification, return an HTTP 2xx status code and SUCCESS in the response body.

4.4 Notification Example

{
  "platform_order_no": "PO20240601000001",
  "merchant_order_no": "MCH202406010001",
  "merchant_id": 10001,
  "amount": 1000000,
  "actual_amount": 1000000,
  "success_amount": 1000000,
  "status": 3,
  "fail_reason": "",
  "currency": "RMB"
}

4.5 Merchant Response

The platform considers the notification successful only when both conditions are met: the HTTP status code is 2xx, and the response body is SUCCESS.

Merchant Response	Platform Handling
HTTP 2xx with response body SUCCESS	Notification successful
Non-2xx HTTP status, or response body is not SUCCESS	Notification failed. The response is recorded.
Timeout or network error	Notification failed. The error is recorded.

Response example:

SUCCESS

4.6 Idempotency

Use platform_order_no or merchant_order_no as the unique identifier when processing callback notifications. The same order may be notified more than once due to network retries or manual resend. Your system must avoid duplicate balance changes or duplicate order updates.

4.7 Notes

1. Asynchronous notifications do not include an extra sign field. Use HTTPS, IP whitelist, and order information validation to protect callback security.
2. amount, actual_amount, and success_amount are integer amounts. Unit: 0.0001 CNY.
3. The callback endpoint should respond as quickly as possible. If processing takes more than 10 seconds, the platform may treat the notification as failed.

---

5. Status Codes

5.1 Common Status Codes

code	Description
0	Success
200026	Signature verification failed
Other	Business failure. See msg for details.

5.2 Order State

state	Description
0	Pending
1	Processing
2	Reserved. Merchants do not need to treat it as a final state.
3	Success
4	Failed
5	Rejected
6	Reversed
7	Processing

States 3, 4, 5, and 6 are final states. Handle final-state notifications idempotently.

---

6. Integration Process

6.1 Apply for Merchant Account

1. Contact the platform to apply for a merchant account.
2. Obtain the merchant number and merchant secret.
3. Configure request IP whitelist and callback URL.

6.2 Development Integration

1. Implement signature generation according to this document.
2. Integrate payout order creation, order query, and balance query APIs.
3. Implement the asynchronous notification receiving API and return SUCCESS after successful processing.
4. Ensure idempotent handling for order numbers and callback notifications.

6.3 Testing

1. Use test merchant number and secret to send requests.
2. Confirm amount unit, signature, and timestamp format.
3. Verify order creation, query, balance query, and asynchronous notification workflows.

6.4 Go Live

1. Switch to production merchant number and secret.
2. Configure production callback URL.
3. Check server IP whitelist.
4. Keep request and callback logs for troubleshooting.

---

7. FAQ

7.1 What should I do if signature verification fails?

1. Confirm that sign is not included in the signature string.
2. Confirm fields are concatenated in ASCII ascending order.
3. Confirm empty fields are excluded.
4. Confirm the correct merchant secret is appended.
5. Confirm the final MD5 result is converted to 32-character uppercase.

7.2 Why cannot amount be passed as a decimal?

The API uses integer amount units. The unit is 0.0001 CNY. For example, real amount 1 CNY should be passed as 10000.

7.3 What happens if the order number is duplicated?

mchOrderNo is the unique merchant-side order number. Duplicate submissions of the same order number will be recognized as duplicate orders. Merchants should ensure global uniqueness.

7.4 Which order number should be used for order query?

Prefer the platform payoutOrderId. If it is not saved, mchOrderNo can also be used.

7.5 What should I do if callbacks cannot be received?

1. Check whether notifyUrl is publicly accessible.
2. Check whether the callback API can return HTTP 2xx and SUCCESS within 10 seconds.
3. Check whether the callback API times out or returns errors.
4. Check platform order logs and merchant service logs.

---

8. Contact

For any questions, contact platform technical support.

---

Document Version: v1.0

Last Updated: 2026-06-25