Xunhu Pay

https://www.xunhupay.com/doc/
Admin
Xunhu Pay is a payment gateway API platform that enables developers to integrate payment processing,...
Tokens:4,067
Snippets:12
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### API Response Examples

Source: https://www.xunhupay.com/doc/api/pay.html

JSON response structures for successful and failed payment initiation requests.

```json
{
            "openid":"2019081202",
    		"url":"https:\/\/api.xunhupay.com\/alipay\/pay\/index.html?id=20351731&nonce_str=3642452019&time=1522390464&appid=20146122002&hash=ef07fb856239c6066a8c84c21835e047",
    		"errcode":0,
    		"errmsg":"success!",
    		"hash":"3a91e22ee359c914b0788c6007377638"
}
```

```json
{
    		"errcode":500,
    		"errmsg":"invalid sign!",
    		"hash":"3a91e22ee359c914b0788c6007377638"
}
```

--------------------------------

### API Response Examples

Source: https://www.xunhupay.com/doc/api/search.html

JSON response structures for successful and failed API requests.

```json
{
    		"errcode":0,
            "data":{
            	"status":"OD",
                "open_order_id":"xxxx"
                ...
            },
    		"errmsg":"success!",
    		"hash":"3a91e22ee359c914b0788c6007377638"
    		}
```

```json
{
    		"errcode":500,
    		"errmsg":"invalid sign!",
    		"hash":"3a91e22ee359c914b0788c6007377638"
    		}
```

--------------------------------

### Initiate Payment API

Source: https://www.xunhupay.com/doc/api/pay.html

This API is used to initiate a payment transaction. It requires various parameters including order details, user information, and security hashes. The response provides a payment URL or QR code for the user to complete the transaction.

```APIDOC
## POST /payment/do.html

### Description
Initiates a payment transaction and returns a payment URL or QR code.

### Method
POST

### Endpoint
`https://api.xunhupay.com/payment/do.html` or `https://api.dpweixin.com/payment/do.html`

### Parameters
#### Request Body
- **version** (string(24)) - Required - API Version number, currently 1.1
- **appid** (string(32)) - Required - Xunhupay APP ID
- **trade_order_id** (string(32)) - Required - Unique merchant order ID (alphanumeric, _, -, *)
- **total_fee** (decimal(18,2)) - Required - Order amount in CNY (no decimal places required)
- **title** (string(128)) - Required - Order title (max 127 chars or 42 Chinese chars, no emojis or %)
- **time** (int(11)) - Required - Current timestamp (e.g., PHP `time()`)
- **notify_url** (string(128)) - Required - Server-to-server callback URL for payment success notification
- **return_url** (string(128)) - Optional - User browser redirect URL upon successful payment
- **callback_url** (string(128)) - Optional - User browser redirect URL if payment is cancelled
- **plugins** (string(128)) - Optional - Identifier for the integration program or author
- **attach** (text) - Optional - Remark field, returned as is in callback
- **nonce_str** (string(32)) - Required - Random string to prevent caching and guessing of security keys
- **hash** (string(32)) - Required - Signature of the request parameters

### Request Example
```json
{
  "version": "1.1",
  "appid": "20146122002",
  "trade_order_id": "M19081200001",
  "total_fee": "1.00",
  "title": "Test Order",
  "time": 1522390464,
  "notify_url": "http://yourdomain.com/notify.php",
  "return_url": "http://yourdomain.com/return.php",
  "nonce_str": "3642452019",
  "hash": "ef07fb856239c6066a8c84c21835e047"
}
```

### Response
#### Success Response (200)
- **orderid** (int) - Order ID (historical field, usually not needed)
- **url_qrcode** (string(156)) - QR code URL for PC payment (valid for 5 minutes)
- **url** (string(155)) - Payment URL for mobile devices
- **errcode** (int) - Error code (0 for success)
- **errmsg** (string(8)) - Error message
- **hash** (string(32)) - Signature of the response parameters

#### Response Example (Success)
```json
{
  "orderid": "2019081202",
  "url": "https:\/\/api.xunhupay.com\/alipay\/pay\/index.html?id=20351731&nonce_str=3642452019&time=1522390464&appid=20146122002&hash=ef07fb856239c6066a8c84c21835e047",
  "errcode": 0,
  "errmsg": "success!",
  "hash": "3a91e22ee359c914b0788c6007377638"
}
```

#### Response Example (Failure)
```json
{
  "errcode": 500,
  "errmsg": "invalid sign!",
  "hash": "3a91e22ee359c914b0788c6007377638"
}
```

### HASH Generation
1. Sort all non-empty parameters by key in ASCII order.
2. Concatenate them into a string `stringA` in `key=value` format.
3. Append your `APPSECRET` to `stringA` to get `stringSignTemp`.
4. Calculate the MD5 hash of `stringSignTemp` (32-bit lowercase).

**Note**: The `hash` parameter itself should not be included in the signature calculation when verifying.
```

--------------------------------

### Initiate Order Refund API

Source: https://www.xunhupay.com/doc/api/refund.html

This API endpoint allows merchants to initiate a refund for a previously placed order. It supports multiple platform URLs and requires specific parameters for authentication and refund details.

```APIDOC
## POST /payment/refund

### Description
Initiates a refund for a specified order. This endpoint can be accessed via multiple platform URLs.

### Method
POST

### Endpoint
- `https://api.xunhupay.com/payment/refund.html` (Official Platform)
- `https://api.dpweixin.com/payment/refund.html` (Backup Platform)
- `https://api.diypc.com.cn/payment/refund.html` (Other Platforms)

### Parameters
#### Request Body
- **appid** (string(32)) - Required - Application ID.
- **trade_order_id** (string(32)) - Required - Merchant website order number. Either `trade_order_id` or `open_order_id` must be provided. Ensure this is unique within your system.
- **open_order_id** (string(32)) - Required - Xunhuapay internal order number. Either `trade_order_id` or `open_order_id` must be provided. This is returned upon successful payment.
- **reason** (string(80)) - Optional - The reason for the refund. If provided, this reason will be displayed in the refund message sent to the user by WeChat.
- **time** (int(11)) - Required - Current timestamp (e.g., `time()` in PHP).
- **nonce_str** (string(32)) - Required - A random string used to prevent server-side caching and protect against security key guessing.
- **hash** (string(32)) - Required - Signature generated using the provided algorithm.

### Request Example
```json
{
  "appid": "your_appid",
  "trade_order_id": "merchant_order_123",
  "reason": "Customer requested refund",
  "time": 1678886400,
  "nonce_str": "random_string_here"
}
```

### Response
#### Success Response (200)
- **trade_order_id** (string(32)) - Merchant website order number.
- **transaction_id** (string(32)) - Transaction number.
- **out_refund_no** (string(32)) - Refund order number.
- **refund_fee** (decimal(9,2)) - Refund amount.
- **reason** (string(80)) - Refund reason.
- **refund_status** (string(2)) - Refund status: OD (Paid), CD (Refunded), RD (Refunding), UD (Refund Failed).
- **refund_time** (string(16)) - Refund timestamp.
- **errcode** (int) - Error code.
- **errmsg** (string(8)) - Error message.
- **hash** (string(32)) - Data signature.

#### Response Example
```json
{
  "trade_order_id": "merchant_order_123",
  "transaction_id": "wx_transaction_id_abc",
  "out_refund_no": "refund_order_xyz",
  "refund_fee": "10.00",
  "reason": "Customer requested refund",
  "refund_status": "CD",
  "refund_time": "2023-03-15 10:00:00",
  "errcode": 0,
  "errmsg": "Success",
  "hash": "generated_signature"
}
```

### HASH Generation Steps
1. **Sort Parameters**: Collect all non-empty request parameters (excluding `hash`). Sort them by parameter name in ascending ASCII order (case-sensitive). Concatenate them into a string in `key1=value1&key2=value2` format.
2. **Append Secret**: Append your `APPSECRET` to the end of the sorted string.
3. **MD5 Hash**: Calculate the MD5 hash of the resulting string. This is your `hash` value.

**Important Rules for Hashing:**
- Parameter names are case-sensitive.
- Empty parameter values are not included in the signature.
- The `sign` parameter itself is not included when verifying signatures.
- The API may introduce new fields; your verification must support these.

### HASH Generation Example (PHP)
```php
function generate_xh_hash(array $datas, $hashkey) {
    ksort($datas);
    reset($datas);

    $pre = array();
    foreach ($datas as $key => $data) {
        if (is_null($data) || $data === '') {
            continue;
        }
        if ($key === 'hash') {
            continue;
        }
        // stripslashes removes extra slashes from PHP POST requests (may not be needed in other languages)
        $pre[$key] = stripslashes($data);
    }

    $arg = '';
    $qty = count($pre);
    $index = 0;

    foreach ($pre as $key => $val) {
        $arg .= "$key=$val";
        if ($index++ < ($qty - 1)) {
            $arg .= "&";
        }
    }

    return md5($arg . $hashkey);
}
```
```

--------------------------------

### Payment Gateway URLs

Source: https://www.xunhupay.com/doc/api/pay.html

The base URLs for the production and backup payment gateway environments.

```text
正式环境：https://api.xunhupay.com/payment/do.html   
备用平台：https://api.dpweixin.com/payment/do.html (设置为可配置的变量，以便接口变更时方便修改)
```

--------------------------------

### POST /payment/query

Source: https://www.xunhupay.com/doc/api/search.html

This endpoint allows you to query the status of a payment order. You can use either your own `out_trade_order` or the `open_order_id` provided by Xunhupay.

```APIDOC
## POST /payment/query

### Description
This endpoint is used to query the status of a payment order. It accepts POST requests and returns a JSON response.

### Method
POST

### Endpoint
`https://api.xunhupay.com/payment/query.html` (Formal Platform)
`https://api.dpweixin.com/payment/query.html` (Backup Platform)
`https://api.diypc.com.cn/payment/query.html` (Other Platforms - recommended to request once every 5-10 seconds, maximum once every 10 minutes)

### Parameters
#### Query Parameters
- **appid** (string(32)) - Required - Your application ID.
- **out_trade_order** (string(32)) - Optional - Your unique order number. Mutually exclusive with `open_order_id`.
- **open_order_id** (string(32)) - Optional - Xunhupay's internal order number. Mutually exclusive with `out_trade_order`.
- **time** (int(11)) - Required - Current timestamp (e.g., `time()` in PHP).
- **nonce_str** (string(32)) - Required - A random string to prevent caching and guessing of security keys.
- **hash** (string(32)) - Required - The signature generated for the request.

### HASH Generation
1. **Sort Parameters**: Collect all non-empty parameters (excluding `hash`) and sort them by parameter name in ascending ASCII order. Concatenate them into a string in `key1=value1&key2=value2` format.
2. **Append Secret**: Append your `APPSECRET` to the end of the sorted string.
3. **MD5 Hash**: Calculate the MD5 hash of the resulting string.

**Note**: Parameter names are case-sensitive. Empty parameter values are not included in the signature. When verifying a signature, the `sign` parameter itself is not included.

### Request Example
```json
{
  "appid": "your_appid",
  "out_trade_order": "your_order_id",
  "time": 1678886400,
  "nonce_str": "random_string",
  "hash": "generated_hash"
}
```

### Response
#### Success Response (200)
- **errcode** (int) - 0 for success.
- **data** (object) - Contains order details.
  - **status** (string) - Order status: `OD` (Paid), `WP` (Pending Payment), `CD` (Cancelled).
  - **open_order_id** (string) - Xunhupay's internal order ID.
- **errmsg** (string) - Success message (e.g., "success!").
- **hash** (string) - Signature of the response.

#### Success Response Example
```json
{
    "errcode": 0,
    "data": {
        "status": "OD",
        "open_order_id": "xxxx"
    },
    "errmsg": "success!",
    "hash": "3a91e22ee359c914b0788c6007377638"
}
```

#### Error Response Example
```json
{
    "errcode": 500,
    "errmsg": "invalid sign!",
    "hash": "3a91e22ee359c914b0788c6007377638"
}
```
```

--------------------------------

### Generate Security Hash in PHP

Source: https://www.xunhupay.com/doc/api/search.html

Function to generate a MD5 hash for API requests. It sorts parameters by ASCII order and appends the APPSECRET before hashing.

```php
function generate_xh_hash(array $datas,$hashkey){
                    ksort($datas);
                    reset($datas);

                    $pre =array();
                    foreach ($datas as $key => $data){
                        if(is_null($data)||$data===''){continue;}

                        if($key=='hash'){
                            continue;
                        }

						//stripslashes 去除php POST请求自带的多余斜杠(其他语言可以不处理)
                        $pre[$key]=stripslashes($data);
                    }

                    $arg  = '';
                    $qty = count($pre);
                    $index=0;

                    foreach ($pre as $key=>$val){
                        $arg.="$key=$val";
                        if($index++<($qty-1)){
                            $arg.="&";
                        }
                    }

                    return md5($arg.$hashkey);
                }
```

--------------------------------

### Order Query API Endpoints

Source: https://www.xunhupay.com/doc/api/search.html

List of available API endpoints for order status queries. It is recommended to poll these endpoints every 5-10 seconds, with a maximum duration of 10 minutes.

```text
正式平台：https://api.xunhupay.com/payment/query.html  
备用平台：https://api.dpweixin.com/payment/query.html  
其他平台：https://api.diypc.com.cn/payment/query.html(建议5-10秒请求一次，最长不超过10分钟)
```

--------------------------------

### Payment Success Callback Notification

Source: https://www.xunhupay.com/doc/api/pay.html

This endpoint is called by Xunhupay's server when a user successfully completes a payment. Your server should respond with 'success' to acknowledge receipt. If 'success' is not returned, Xunhupay will retry the notification up to 6 times.

```APIDOC
## POST /notify.php (Example Callback URL)

### Description
Receives payment success notifications from Xunhupay.

### Method
POST

### Parameters
#### Request Body (form-data)
- **trade_order_id** (string(32)) - Required - Merchant order ID from the payment request
- **total_fee** (decimal(18,2)) - Required - The amount paid for the order
- **transaction_id** (string(32)) - Required - Xunhupay's internal transaction ID
- **open_order_id** (string(32)) - Required - Xunhupay's internal order ID
- **order_title** (string(32)) - Required - Title of the order
- **status** (string(2)) - Required - Order status (`OD`=Paid, `CD`=Refunded, `RD`=Refunding, `UD`=Refund Failed)
- **plugins** (string(128)) - Optional - Plugin ID, if provided in the payment request
- **attach** (text) - Optional - Remark field, if provided in the payment request
- **appid** (string(32)) - Required - Payment channel App ID
- **time** (string(16)) - Required - Timestamp of the notification
- **nonce_str** (string(16)) - Required - Random string
- **hash** (string(32)) - Required - Signature of the callback parameters (use the same algorithm as payment initiation)

### Response
- Return `success` to acknowledge receipt. Any other response will trigger retries.
```

--------------------------------

### Generate HASH Signature

Source: https://www.xunhupay.com/doc/api/pay.html

PHP function to generate a 32-character MD5 hash for request verification, following ASCII sorting of parameters.

```php
function generate_xh_hash(array $datas,$hashkey){
 					ksort($datas);
                    reset($datas);
                    $arg  = '';
                    foreach ($datas as $key=>$val){
                    	if($key=='hash'||is_null($val)||$val===''){continue;}
                   	    if($arg){$arg.='&';}
                        $arg.="$key=$val";
                    }

                    return md5($arg.$hashkey);
}
```
Tokens:
Raw