Overview

Supports refund requests and queries, including full and partial refunds, with comprehensive tracking and history.

Features

• 🎯 Flexible refund requests：Full, partial, or multi-item refunds.
• ⚡ Fast review process：Automated and manual checks.
• 📊 Real-time tracking of refund status：Real-time tracking of refund status.
• 📝 Detailed record and analytics：Detailed record and analytics.
• 🔔 Notifications on refund status updates：Notifications on refund status updates.

Refund Types

Refunds can be divided into two types:

• Partial Refund：Less than total payment, can be issued multiple times.
• Full Refund：Equal to total payment amount.

Refund Request

Refund Method

1. API Refund: Suitable for merchants with a large number of orders who want to automate the process. Data can be submitted directly through the system.
2. Manual Refund via Merchant backend: Merchants can initiate refunds manually.

Flow Chart

Initiate Refund

The merchant server calls the refund function and initiates a full or partial refund through the refund_type parameter:

curl -X POST '/service/applyRefund'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'account=995149'
-d 'terminal=99514901'
-d 'signValue=6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b'
-d 'payment_id=180803140041683010528'
-d 'refund_type=1'
-d 'refund_amount=0.01'
-d 'refund_description=refund'

Response Data

<?xml version="1.0" encoding="utf-8"?>
<response> 
  <account>995149</account>  
  <terminal>99514901</terminal>  
  <signValue>d40141ae503344826e29256cb3f3992d4566b439042d461f7593dc4f2ddee3cd</signValue>  
  <payment_id>180724171417837026022</payment_id>  
  <order_number/>  
  <refund_number/>  
  <refund_id>0</refund_id>  
  <refund_results>41</refund_results>  
  <refund_description>Refund request has exceeded the acceptable refund period</refund_description>  
  <refund_reference/> 
</response>

Refund Result

Parameter	Description
refund_results	Refund request result
refund_description	Reason for refund result

• View the complete response parameters.

Note

If insufficient balance, refunds enter a pending queue with four daily checks. After 30 days, unprocessed refunds are marked as failed. Refund status can also be monitored via query or webhook.

• View full list of refund response parameters →
• You can also receive the refund status via asynchronous notifications.

Refund Usage Guidelines

When initiating a refund request, it is recommended to include the refund_number parameter in the request. This parameter is a unique refund transaction ID generated within the merchant system, used to associate the refund with the original order. It will be returned unchanged in the API response.

Refund Status Description

• When the returned refund_results value is 02: This indicates that the refund request has been accepted for processing. You should not resend the refund request. Please wait for the subsequent asynchronous notification to obtain the final refund result.
• When the returned refund_results value is 25: This indicates that the refund request has failed. You may initiate a new refund request using the same refund_number.

Note

For refund requests associated with the same refund_number, the final result is determined by the last asynchronous notification.

Refund Amount Validation

Before initiating a refund request, ensure that the refund amount is valid and does not exceed the remaining refundable amount of the order.
Example:
Order amount: 10
Refunded amount: 8
Remaining refundable amount: 2
If you initiate another refund, the amount must not exceed 2.

Best Practices

• Generate a unique and traceable refund_number for each refund request.
• Avoid repeated API calls after receiving a 02 (accepted) response.
• Use the asynchronous notification as the final source of truth for refund status. Strictly validate the refund amount before submitting the request to prevent over-refunding.

Refund Query

Flow Chart

Query Refund

1. The merchant server calls the refund query function and initiates the query using the refund_id or refund_number returned from the refund request:

curl -X POST '/service/queryRefund'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'account=995149'
-d 'terminal=99514901'
-d 'signValue=6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b'
-d 'refund_id=180456282544'
-d 'refund_number=180252565585'

Response Data

<?xml version="1.0" encoding="utf-8"?>
<response> 
  <account>995149</account>  
  <terminal>99514901</terminal>  
  <signValue>01b3f015ce8b94b824a5fe7b13e5e0527da60d6bfdf511f632ed4aef8a7bedce</signValue>  
  <refund_id>49</refund_id>  
  <refund_number/>  
  <refund_queryNo/>  
  <refund_check>00</refund_check>  
  <refund_description>Refunded</refund_description> 
</response>

Query Result

Parameter	Description
refund_check	Refund query result code
refund_description	Refund query reason description