tencent cloud

Tencent Cloud Super App as a Service

ドキュメントTencent Cloud Super App as a Service

Mini Program Payment

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-06-10 17:28:46

1. Query order status

API description:

Queries order status using the order number.

Request method: GET

Request URL:

/v3/pay/transactions/out-trade-no/:out_trade_no?mchid=xxx

Request header

Parameter
Required
Description
Note
Authorization
Yes
Signature authentication information.
For more information, see APIv3 Certificate Signature
Content-Type
Yes
application/json
-

Path parameters

Property
Type
‍Required
Description
out_trade_no
string
Yes
Merchant order number, provided when the merchant places the order.

Query parameters

Property
Type
‍Required
Description
mchid
string
Yes
Merchant ID, provided when the merchant places the order.

Response parameters

Property
Type
‍Required
Description
appid
string
Yes
Mini program appid.
mch_id
string
Yes
Merchant ID, provided when the merchant places the order.
out_trade_no
string
Yes
Merchant order number, provided when the merchant places the order.
transaction_id
string
No
Unique identifier of the payment order, which is returned when the order is paid successfully.
trade_type
string
No
Transaction type: JSAPI for mini program payments.
trade_state
string
Yes
Transaction status:
WAIT_PAY - Awaiting payment
SUCCESS - Payment successful
CLOSED - Order closed
AUTO_CLOSED - Order automatically closed due to expiration
REFUND - Refunded
PAY_ERROR - Payment failed


bank_type
string
No
Bank code. Non-bank card payment types are uniformly marked as OTHERS.
attach
string
No
Merchant data packet, custom data provided by the merchant when placing the order, not visible to the user, up to 256 characters. If provided, it will be returned as-is in this API, payment success callback notification, and transaction bill. If not provided, it will not be returned.
success_time
string
No
Payment completion time. It follows the RFC 3339 standard format: YYYY-MM-DDTHH:mm:ss+TIMEZONE. YYYY-MM-DD represents the date; T separates the date and time; HH:mm:ss represents the time; TIMEZONE represents the time zone (e.g., +08:00 for Beijing time).
payer
payer
No
Information about the payer, returned when the order is paid successfully.
amount
object
No
Order amount.
amount.payer_total
string
No
Total order amount (in cents).
amount.total
integer
No
Actual amount paid by the user, an integer value, in cents. User payment amount = total amount - voucher amount.
amount.currency
string
No
Currency type, a three-letter code compliant with ISO 4217.
amount.payer_currency
string
No
Payment currency type, a three-letter code compliant with ISO 4217.

Response example:

{
    "appid": "mpco56h12e6e52hj",
    "mch_id": "mi_7b0a5e40f9",
    "out_trade_no": "2b695106b888d14328d9",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "trade_type": "JSAPI",
    "trade_state": "SUCCESS",
    "bank_type": "OTHERS",
    "attach": "attach info",
    "success_time": "2025-02-28T10:34:56+08:00",
    "payer": {
        "openid": "o910d4edeee717377adguZS89513"
    },
    "amount": {
        "payer_total": "88800",
        "total": 88800,
        "currency": "USD",
        "payer_currency": "USD"
    }
}

2. Close an order

API description:

Closes the original order to avoid duplicate payments when a merchant's order payment fails, and a new order number is generated to re-initiate the payment.
Additionally, if the user payment times out after the system places an order and the system exits without further processing, the close order API should be called to prevent the user from continuing the payment.

Request method: POST

Request URL:

/v3/pay/transactions/out-trade-no/:out_trade_no/close

Request header

Parameter
Required
Description
Note
Authorization
Yes
Signature authentication information.
For more information, see APIv3 Certificate Signature
Content-Type
Yes
application/json
-

Path parameters

Property
Type
‍Required
Description
out_trade_no
string
Yes
Merchant order number, provided when the merchant places the order.

Request parameters

Property
Type
‍Required
Description
mch_id
string
Yes
Merchant ID, provided when the merchant places the order.

Response parameters

Not supported

Response example:

No response packet
204 No Content


3. Place an order in a mini program

API description:

In the mini program payment scenario, merchants need to call this API to place an order in the application and generate a prepay transaction session identifier (prepay_id) used to initiate the payment.

Request method: POST

Request URL:

/v3/pay/transactions/jsapi

Request header

Parameter
Required
Description
Description
Authorization
Yes
Signature authentication information.
For more information, see APIv3 Certificate Signature
Content-Type
Yes
application/json
-

Request parameters

Property
Type
‍Required
Description
appid
string
Yes
Mini program appid.
description
string
Yes
Product description, up to 127 characters.
out_trade_no
string
Yes
Internal order number in the merchant system, must be 6-32 characters long, can only include numbers, uppercase and lowercase letters, _-|*, and must be unique within the same merchant ID.
time_expire
string
Yes
1. Definition: The payment end time is the last time the user can complete the payment for this order, not the order closing time. After this time, the user will not be able to pay for the order. To close an order, call the order closing API.

2. Format requirements: The payment end time shall follow the RFC 3339 standard format: yyyy-MM-DDTHH:mm:ss+TIMEZONE. YYYY-MM-DD represents the date; T separates the date and time; HH:mm:ss represents the time; TIMEZONE represents the time zone (e.g., +08:00 for Beijing time).
3. Parameters can only be configured when the user first places an order, and subsequent modifications are not allowed, attempts to modify will result in errors.
If the actual payment time exceeds the set payment end time, the merchant needs to place a new order with a new merchant order number for the user to pay. If the payment end time has not been exceeded, the original parameters can be used to request the order API again to get the latest prepay_id for payment.
The payment end time cannot be earlier than 1 minute after the order time. If the set payment end time is earlier, the system will automatically adjust it to 1 minute after the order time.
attach
string
No
Custom data packet provided by the merchant when creating the order, not visible to the user, used to store merchant custom information related to the order, with a total length limit of 128 characters. This field will be returned to the merchant in the order query API and payment success callback notification, and will also appear in the transaction bill.
notify_url
string
Yes
The URL where the merchant receives payment success callback notifications. It must comply with the guidelines for setting notify_url.
amount
object
Yes
Order amount.
amount.total
integer
No
Actual amount paid by the user, an integer value, in cents. User payment amount = total amount - voucher amount.
amount.currency
string
No
Currency type, a three-letter code compliant with ISO 4217.
payer
object
Yes
Payer information.
payer.openid
string
No
A unique identifier for each user within a single merchant's mini program appid. The user's openid must be obtained before placing an order. For details, see Mini Program Login
detail
object
Yes
Discount feature.
detail.cost_price
integer
No
Original price of the order.
detail.goods_detail
array[object]
No
List of individual product details.
detail.goods_detail.merchant_goods_id
string
No
Unified product ID defined by the payment system (optional).
detail.goods_detail.goods_name
string
No
Actual product name.
detail.goods_detail.quantity
integer
Yes
Quantity of products purchased by the user.
detail.goods_detail.unit_price
integer
Yes
Integer, unit: cents. If the merchant offers a discount, the discounted unit price should be provided (e.g., if a user uses a 100-50 coupon on a 100 USD order, the unit price of the promotional product should be the original unit price minus 50).

Response parameters

Property
Type
‍Required
Description
prepay_id
string
Yes
Prepay transaction session identifier, required for JSAPI or mini program payment initiation, valid for 2 hours. If it expires, a new prepay_id must be requested by calling this API again.

Response example:

{
    "prepay_id":"pi173898442419368bhz26jn4rikpwzr1akn"
}

4. Payment callback

API description:

When a user successfully pays for an order, the application payment system will send a callback notification to the merchant's pre-configured callback URL (notify_url) via a POST request, informing the merchant that the user has completed the payment.

Request method: POST

Request URL:

The notify_url passed in by the order API.

Request header

Parameter
Description
Note
Pay-Serial
The serial number of the superapp payment certificate used for verification.
-
Pay-Signature
Signature verification value.
For signature verification, see Superapp Payment Certificate Signature
Pay-Timestamp
Timestamp for verification.
-
Pay-Nonce
Random string for verification.
-

Request parameters

Property
Type
‍Required
Description
id
string
Yes
Unique identifier for the callback notification.
create_time
string
Yes
The time when the callback notification was created.
Format: Follow the RFC 3339 standard format: YYYY-MM-DDTHH:mm:ss+TIMEZONE. YYYY-MM-DD represents the date; T separates the date and time; HH:mm:ss represents the time; TIMEZONE represents the time zone (e.g., +08:00 corresponds to UTC+8).
Example: 2015-05-20T13:29:35+08:00 represents 13:29:35 on May 20, 2015 (UTC+8).
resource_type
string
Yes
Resource data type of the notification. It is fixed as encrypt-resource.

event_type
string
Yes
Type of payment callback notification.
For successful payment notifications, the type is TRANSACTION.SUCCESS.
pay_model
string
No
Type of payment bank card, OTHERS for non-bank card payments.
summary
string
Yes
The summary note for callback content in the payment system, limited to 64 characters.
Resource
object
Yes
Notification resource data.
resource.original_type
string
Yes
Original callback type: The object type before encryption, which is transaction.
resource.algorithm
string
Yes
Encryption algorithm type for the callback data ciphertext. It is currently AEAD_AES_256_GCM. Developers need to use the same type of data for decryption.
resource.ciphertext
string
Yes
Data ciphertext: The Base64-encoded ciphertext of the callback data. Merchants need to Base64 decode and decrypt it. For more information, see Decrypt Callback Messages.
resource.associated_data
string
No
Additional data for decryption, this field may be empty.
resource.nonce
string
Yes
Random string involved in decryption.

Response parameters

Property
Type
‍Required
Description
ok
string
Yes
-

Response example:

{
  "ok"
}

Data type

Decrypted structure of resource.ciphertext data:

After decrypting resource.ciphertext in the standard payment callback using AEAD_AES_256_GCM, the following JSON object is obtained (consistent with the query order response structure):
Property
Type
‍Required
Description
appid
string
Yes
Mini program appid.
merchant_id
string
Yes
Merchant ID.
out_trade_no
string
Yes
Merchant order number.
transaction_id
string
Yes
Transaction ID on the superapp side.
trade_type
string
No
Transaction type: JSAPI for mini program payments.
trade_state
string
Yes
Transaction status. Valid values: SUCCESS: Payment successful; CLOSED: Closed; PAY_ERROR: Payment failed.
bank_type
string
No
Bank code. Non-bank card payment types are uniformly marked as OTHERS.
attach
string
No

success_time
string
No
Payment completion time. Format: YYYY-MM-DDTHH:MM:SS+TIMEZONE.
payer
object
No
Payer information.
payer.openid
string
No
A unique identifier for each user within a single merchant's mini program appid.
amount
object
No
Order amount.
amount.payer_total
string
No
The actual amount paid by the user (in cents).
amount.total
string
No
Total order amount (in cents).
amount.currency
string
No
Currency type, a three-letter code compliant with ISO 4217.
amount.payer_currency
string
No
The currency used by the user for the payment.

Decrypted data example

{
    "appid": "mpco56h12e6e52hj",
    "merchant_id": "mi_7b0a5e40f9",
    "out_trade_no": "2b695106b888d14328d9",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "trade_type": "JSAPI",
    "trade_state": "SUCCESS",
    "bank_type": "OTHERS",
    "attach": "attach info",
    "success_time": "2025-02-28T10:34:56+08:00",
    "payer": {
        "openid": "o910d4edeee717377adguZS89513"
    },
    "amount": {
        "payer_total": "88800",
        "total": "88800",
        "currency": "USD",
        "payer_currency": "USD"
    }
}

Notes on notify_url

(1) The notify_url should be the actual address of the merchant's own system, not an example address from the API documentation or demo.
(2) The notify_url must be a complete URL starting with either https:// or http://. Ensure that the domain and IP in the URL are accessible from the internet; do not use localhost, 127.0.0.1, 192.168.x.x, or any local or internal network IPs.
(3) The notify_url should not include any parameters.
Common errors:
Error description
Error example
URL only contains a domain, missing a specific path.
http://www.domain.com
URL does not start with https:// or http://, missing domain or IP.
./PayNotify.aspx
URL contains a local or internal network IP.
http://127.0.0.1/pay/notify.php
The string entered is not in URL format.
xxxxxxx, 1234567, test
Notes on callback handling logic
The backend code handling the notify_url should not include login state verification.
Upon receiving a payment result notification, the merchant system must respond within 5 seconds. Otherwise, the application payment system will consider the notification failed and will resend it.
The same notification may be sent multiple times to the merchant system. The merchant system must correctly handle duplicate notifications. If the notification has already been processed, directly return a success response to the payment system.

5. Standard payment - Apply for refund

API description:

When a refund is needed after a transaction, the merchant can use this API to refund the payment amount to the buyer. Both partial and full refunds are supported.

Request method: POST

Request URL:

/spay/refund/refunds

Request header

Parameter
Required
Description
Note
Authorization
Yes
Signature authentication information.
For more information, see APIv3 Certificate Signature
Content-Type
Yes
application/json
-

Request parameters

Property
Type
‍Required
Description
merchant_id
string
Yes
Merchant ID.
transaction_id
string
No
Transaction ID on the superapp side (Either this or out_trade_no must be provided.)
out_trade_no
string
No
Merchant order number, either this or transaction_id must be provided.
out_refund_no
string
Yes
Merchant refund number. Must be unique under the same merchant ID.
reason
string
No
Refund reason.
notify_url
string
No
Refund result notification URL.
amount.refund
integer
Yes
Refund amount (in cents).
amount.total
integer
Yes
Total amount of the original order (in cents).
amount.currency
string
Yes
Currency type, a three-letter code compliant with ISO 4217.
goods_detail[].merchant_goods_id
string
No
Merchant's product code.
goods_detail[].goods_name
string
No
Product name.
goods_detail[].unit_price
integer
No
Product unit price (in cents).
goods_detail[].refund_amount
integer
No
Refund amount (in cents).
goods_detail[].refund_quantity
integer
No
Number of items refunded.

Response parameters

Property
Type
‍Required
Description
refund_id
string
Yes
Refund ID on the superapp side.
out_refund_no
string
Yes
Merchant refund number.
transaction_id
string
Yes
Transaction ID on the superapp side.
out_trade_no
string
Yes
Merchant order number.
channel
string
Yes
Refund channel. Valid values: ORIGINAL: Refund to original payment method; BALANCE: Refund to balance; OTHER_BALANCE: Refund to another balance account; OTHER_BANKCARD: Refund to another bank card.
user_received_account
string
Yes
Account receiving the refund funds.
success_time
string
No
Refund success time. Returned only when status is SUCCESS. Format: YYYY-MM-DDTHH:mm:ss+TIMEZONE.
create_time
string
Yes
Refund creation timestamp.
status
string
Yes
Refund status. Valid values: PROCESSING: Processing; SUCCESS: Succeeded; CLOSED: Closed; ABNORMAL: Abnormal.
amount.total
integer
Yes
Total order amount (in cents).
amount.refund
integer
Yes
Refund amount (in cents).
amount.payer_total
integer
Yes
Amount paid by user (in cents).
amount.payer_refund
integer
Yes
Refund amount to user (in cents).
amount.currency
string
Yes
Currency type.

Response example:

{
    "refund_id": "rf17389154493510001",
    "out_refund_no": "refund_2b695106b888",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "out_trade_no": "2b695106b888d14328d9",
    "channel": "ORIGINAL",
    "user_received_account": "Account receiving the refund funds",
    "create_time": "2025-02-28T11:00:00+08:00",
    "status": "PROCESSING",
    "amount": {
        "total": 88800,
        "refund": 44400,
        "payer_total": 88800,
        "payer_refund": 44400,
        "currency": "USD"
    }
}

6. Virtual payment - Apply for refund

API description:

Refund request for virtual payment scenarios. Uses virtual payment signature verification (access_token + pay_sig). The request parameters include additional fields: openid and req_from.

Request method: POST

Request URL:

/vpay/refund/refunds?access_token={access_token}&pay_sig={pay_sig}

Request header

Parameter
Required
Description
Note
Content-Type
Yes
application/json
-

Request parameters

Property
Type
‍Required
Description
mch_id
string
Yes
Merchant ID.
openid
string
Yes
User's openid at the time of order placement.
transaction_id
string
No
Transaction ID on the superapp side (Either this or out_trade_no must be provided.)
out_trade_no
string
No
Merchant order number, either this or transaction_id must be provided.
out_refund_no
string
Yes
Merchant refund number. Uniquely identifies a refund.
reason
string
No
Refund reason.
notify_url
string
No
Refund result notification URL.
amount.refund
integer
Yes
Refund amount (in cents).
amount.total
integer
Yes
Total amount of the original order (in cents).
amount.currency
string
Yes
Currency type.
req_from
string
No
Refund source. Valid values: 1: Customer service-initiated; 2: User-initiated; 3: Other.

Response parameters

Property
Type
‍Required
Description
code
string
Yes
Return code. 0: Request successful.
messages
string
Yes
Return message.
request_id
string
Yes
Request ID.
refund_id
string
Yes
Refund ID on the superapp side.
out_refund_no
string
Yes
Merchant refund number.

Response example:

{
    "code": "0",
    "message": "success",
    "request_id": "req_xxxx",
    "refund_id": "rf17389154493510002",
    "out_refund_no": "vrefund_2b695106"
}

7. Standard payment - Query refund

API description:

After submitting a refund request, call this API to query the standard payment refund status.

Request method: GET

Request URL:

/spay/refund/refunds/:out_refund_no?merchant_id={merchant_id}

Request header

Parameter
Required
Description
Note
Authorization
Yes
Signature authentication information.
For more information, see APIv3 Certificate Signature
Content-Type
Yes
application/json
-

Request parameters

Property
Type
‍Required
Description
out_refund_no
string
Yes
Merchant refund number (path parameter).
merchant_id
string
Yes
Merchant ID (query parameter).

Response parameters

Property
Type
‍Required
Description
refund_id
string
Yes
Refund ID on the superapp side.
out_refund_no
string
Yes
Merchant refund number.
transaction_id
string
Yes
Transaction ID on the superapp side.
out_trade_no
string
Yes
Merchant order number.
channel
string
Yes
Refund channel. Valid values: ORIGINAL: Refund to original payment method; BALANCE: Refund to balance; OTHER_BALANCE: Refund to another balance account; OTHER_BANKCARD: Refund to another bank card.
user_received_account
string
Yes
Account receiving the refund funds.
success_time
string
No
Refund success time. Returned only when status is SUCCESS. Format: YYYY-MM-DDTHH:mm:ss+TIMEZONE.
create_time
string
Yes
Refund creation timestamp.
status
string
Yes
Refund status. Valid values: PROCESSING: Processing; SUCCESS: Succeeded; CLOSED: Closed; ABNORMAL: Abnormal.
amount.total
integer
Yes
Total order amount (in cents).
amount.refund
integer
Yes
Refund amount (in cents).
amount.payer_total
integer
Yes
Amount paid by user (in cents).
amount.payer_refund
integer
Yes
Refund amount to user (in cents).
amount.currency
string
Yes
Currency type.

Response example:

{
    "refund_id": "rf17389154493510001",
    "out_refund_no": "refund_2b695106b888",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "out_trade_no": "2b695106b888d14328d9",
    "channel": "ORIGINAL",
    "user_received_account": "Account receiving the refund funds",
    "success_time": "2025-02-28T11:05:00+08:00",
    "create_time": "2025-02-28T11:00:00+08:00",
    "status": "SUCCESS",
    "amount": {
        "total": 88800,
        "refund": 44400,
        "payer_total": 88800,
        "payer_refund": 44400,
        "currency": "USD"
    }
}

8. Virtual payment - Query refund

API description:

After submitting a refund request, call this API to query the virtual payment refund status.

Request method: GET

Request URL:

/vpay/refund/refunds/:out_refund_no?merchant_id={merchant_id}&access_token={access_token}&pay_sig={pay_sig}

Request parameters

Property
Type
‍Required
Description
out_refund_no
string
Yes
Merchant refund number (path parameter).
merchant_id
string
Yes
Merchant ID (query parameter).
access_token
string
Yes
Mini program API access token (query parameter).
pay_sig
string
Yes
Virtual payment signature (query parameter).

Response parameters

Property
Type
‍Required
Description
refund_id
string
Yes
Refund ID on the superapp side.
out_refund_no
string
Yes
Merchant refund number.
transaction_id
string
Yes
Transaction ID on the superapp side.
out_trade_no
string
Yes
Merchant order number.
channel
string
Yes
Refund channel. Valid values: ORIGINAL: Refund to original payment method; BALANCE: Refund to balance; OTHER_BALANCE: Refund to another balance account; OTHER_BANKCARD: Refund to another bank card.
user_received_account
string
Yes
Account receiving the refund funds.
success_time
string
No
Refund success time. Returned only when status is SUCCESS. Format: YYYY-MM-DDTHH:mm:ss+TIMEZONE.
create_time
string
Yes
Refund creation timestamp.
status
string
Yes
Refund status. Valid values: PROCESSING: Processing; SUCCESS: Succeeded; CLOSED: Closed; ABNORMAL: Abnormal.
amount.total
integer
Yes
Total order amount (in cents).
amount.refund
integer
Yes
Refund amount (in cents).
amount.payer_total
integer
Yes
Amount paid by user (in cents).
amount.payer_refund
integer
Yes
Refund amount to user (in cents).
amount.currency
string
Yes
Currency type.

Response example:

{
    "refund_id": "rf17389154493510002",
    "out_refund_no": "vrefund_2b695106",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "out_trade_no": "2b695106b888d14328d9",
    "channel": "ORIGINAL",
    "user_received_account": "Virtual account",
    "success_time": "2025-02-28T11:05:00+08:00",
    "create_time": "2025-02-28T11:00:00+08:00",
    "status": "SUCCESS",
    "amount": {
        "total": 100,
        "refund": 50,
        "payer_total": 100,
        "payer_refund": 50,
        "currency": "CNY"
    }
}

9. Standard payment - Refund result callback

API description:

After the refund status changes, the superapp platform sends a refund result notification to the merchant's notify_url via POST.

Request method: POST

Request URL:

The notify_url provided by the merchant when applying for the refund.

Request header

Parameter
Description
Description
Pay-Serial
The serial number of the superapp payment certificate used for verification.
-
Pay-Signature
The signature.
For signature verification, see Superapp Payment Certificate Signature
Pay-Timestamp
Timestamp.
-
Pay-Nonce
Random string.
-

Request parameters

Property
Type
‍Required
Description
id
string
Yes
Notification ID.
create_time
string
Yes
Notification creation time.
resource_type
string
Yes
Notification resource type. Fixed value: encrypt-resource.
event_type
string
Yes
Event type. Valid values: REFUND.SUCCESS; REFUND.ABNORMAL; REFUND.CLOSED.
summary
string
Yes
Summary of the callback notification.
resource.algorithm
string
Yes
Encryption algorithm. AEAD_AES_256_GCM.
resource.original_type
string
Yes
Original data type. Fixed value: refund.
resource.ciphertext
string
Yes
Base64-encoded ciphertext data.
resource.nonce
string
Yes
Random string.
resource.associated_data
string
No
Associated data.

Decrypted data

For decryption methods, see Decrypt Callback Messages
Property
Type
‍Required
Description
refund_id
string
Yes
Refund ID on the superapp side.
out_refund_no
string
Yes
Merchant refund number.
transaction_id
string
Yes
Transaction ID on the superapp side.
out_trade_no
string
Yes
Merchant order number.
refund_status
string
Yes
Refund status. Valid values: SUCCESS; CLOSED; ABNORMAL.
success_time
string
No
Refund success time.
user_received_account
string
Yes
Account receiving the refund funds.
amount.total
integer
Yes
Total order amount (in cents).
amount.refund
integer
Yes
Refund amount (in cents).
amount.payer_total
integer
Yes
Amount paid by user (in cents).
amount.payer_refund
integer
Yes
Refund amount to user (in cents).
amount.currency
string
Yes
Currency type.

Response parameters

After successful processing, the merchant must return an acknowledgment to stop notification retries:
{"code": "SUCCESS", "message": "Succeeded"}

10. Virtual payment - Refund result callback

API description:

After the virtual payment refund is completed, the superapp platform sends the refund result notification via POST.

Request method: POST

Request URL:

The notify_url provided by the merchant when applying for the refund.

Request parameters

Property
Type
‍Required
Description
eventType
string
Yes
Event type.
event
string
Yes
Event name.
payMode
string
Yes
Payment mode.
payload
string
Yes
Encrypted callback data.
payEventSig
string
Yes
Callback data signature.

Response parameters

After successful processing, the merchant must return an acknowledgment:
{"code": "SUCCESS", "message": "Succeeded"}

Appendix: Refund validation rules

Property
Type
‍Required
Description
Refund amount.
Validation
Yes
The refund amount for a single refund must not exceed the original order amount.
Refund count
Configuration
Limited
The number of refunds per order is limited by the maxRefundCount configuration.
Refund validity period
Configuration
Limited
Refunds must be submitted within maxRefundDays after payment (default: 365 days).
Idempotency control
Logic
Auto
Requests with identical merchant_id and out_refund_no are deduplicated.
Rate limiting
Logic
Auto
The same merchant_id + out_refund_no cannot be submitted again within one minute (standard payment).
Distributed lock
Logic
Auto
Prevents concurrent duplicate submissions.

Refund status flow

PROCESSING → SUCCESS      (Refund succeeded)
PROCESSING → ABNORMAL     (Refund abnormal)
PROCESSING → CLOSED       (Refund closed)


次の記事へ: データ処理とセキュリティ契約

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック