### Apply for Refund - Heemoney.Refund()

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Initiate a refund request for a successfully paid order. Supports full and partial refunds, with results returned via asynchronous notifications. Ensure the `Out_Refund_No` is unique for each refund attempt.

```csharp
using Heemoney;
using Heemoney.Models.Refund;

// 创建退款请求
RefundRequest refundRequest = new RefundRequest();

// 基础配置
refundRequest.Version = "1";
refundRequest.App_ID = HeemoneyConfig.APP_ID;
refundRequest.Mch_Id = HeemoneyConfig.MCH_ID;
refundRequest.Charset = "gb2312";
refundRequest.Sign_Type = "MD5";
refundRequest.TimeStamp = HeemoneyUtils.GetTimeStamp(DateTime.Now).ToString();

// 退款订单信息
refundRequest.Out_Trade_No = "20231215143052";          // 原商户订单号
refundRequest.Out_Refund_No = "R20231215143052";        // 商户退款单号
refundRequest.Channel_Provider = "WeiXin";              // 原支付渠道
refundRequest.Currency = "CNY";                         // 货币类型
refundRequest.Total_Amt_Fen = "100";                    // 原订单总金额（分）
refundRequest.Bill_TimeOut = "50";                      // 退款金额（分）

// 退款通知地址
refundRequest.Subject = "https://www.example.com/refund_notify";

// 扩展参数
refundRequest.Merch_Extra = "";

// 发起退款请求
RefundResponse refundResponse = Heemoney.Heemoney.Refund(refundRequest);

// 处理响应
if (refundResponse != null && refundResponse.Return_Code == "SUCCESS")
{
    if (refundResponse.Err_Code == "E0000")
    {
        // 退款请求提交成功
        Console.WriteLine("商户订单号: " + refundResponse.Out_Trade_No);
        Console.WriteLine("商户退款单号: " + refundResponse.Out_Refund_No);
        Console.WriteLine("汇收银订单号: " + refundResponse.Hy_Bill_No);
        Console.WriteLine("退款状态: " + refundResponse.Refund_Status);
        Console.WriteLine("退款信息: " + refundResponse.Refund_Msg);
        Console.WriteLine("处理时间: " + refundResponse.Deal_Time);

        // 退款状态判断
        switch (refundResponse.Refund_Status)
        {
            case "SUCCESS":
                Console.WriteLine("退款成功");
                break;
            case "PROCESSING":
                Console.WriteLine("退款处理中，请等待异步通知");
                break;
            case "FAIL":
                Console.WriteLine("退款失败: " + refundResponse.Refund_Msg);
                break;
        }
    }
    else
    {
        Console.WriteLine("退款失败: " + refundResponse.Err_Code_Des);
    }
}

```

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

### Initiate Payment with Heemoney.Pay()

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Use the Heemoney.Pay() method to create a payment request, specifying channel provider, amount, and callback URLs. This method supports various payment channels like WeChat and Alipay.

```csharp
using Heemoney;
using Heemoney.Models.Pay;
using Heemoney.Utils;
using Newtonsoft.Json.Linq;

// 创建支付请求
PayRequest payRequest = new PayRequest();

// 基础配置
payRequest.Version = "1";
payRequest.App_ID = HeemoneyConfig.APP_ID;
payRequest.Mch_Id = HeemoneyConfig.MCH_ID;
payRequest.Charset = "gb2312";
payRequest.Sign_Type = "MD5";
payRequest.TimeStamp = HeemoneyUtils.GetTimeStamp(DateTime.Now).ToString();

// 支付渠道配置
payRequest.Channel_Provider = "WeiXin";      // 支付渠道：WeiXin/AliPay
payRequest.Channel_Code = "WX_NATIVE";       // 支付方式：WX_NATIVE(扫码)/WX_JSAPI(公众号)

// 订单信息
payRequest.Out_Trade_No = DateTime.Now.ToString("yyyyMMddHHmmss");  // 商户订单号
payRequest.Currency = "CNY";                  // 货币类型
payRequest.Total_Amt_Fen = "100";            // 金额（分）
payRequest.Subject = "商品名称";              // 商品标题
payRequest.Subject_Detail = "商品详细描述";   // 商品详情
payRequest.Bill_TimeOut = "6";               // 订单超时时间（分钟）

// 用户信息
payRequest.User_Ip = "127.0.0.1";            // 用户IP
payRequest.User_Identity = "";               // 用户标识（公众号支付时为openid）

// 回调地址
payRequest.Notify_Url = "https://www.example.com/notify";  // 异步通知地址
payRequest.Return_Url = "https://www.example.com/return";  // 同步跳转地址

// 扩展参数
payRequest.Merch_Extra = "";                 // 商户扩展参数
payRequest.Meta_Option = "";                 // 元数据选项
payRequest.Pay_Option = "";                  // 支付选项

// 发起支付请求（第二个参数为true表示测试模式）
PayResponse payResponse = Heemoney.Heemoney.Pay(payRequest, false);

// 处理响应
if (payResponse != null && payResponse.Return_Code == "SUCCESS")
{
    if (payResponse.Err_Code == "E0000")
    {
        // 支付请求成功
        Console.WriteLine("商户订单号: " + payResponse.Out_Trade_No);
        Console.WriteLine("汇收银订单号: " + payResponse.Hy_Bill_No);
        Console.WriteLine("交易状态: " + payResponse.Trade_Status);

        // 解析支付链接
        var jObject = JObject.Parse(payResponse.Hy_Pay_Extra);
        string pageUrl = jObject["page_url"]?.ToString();
        string qrCodeUrl = jObject["qr_code"]?.ToString();

        Console.WriteLine("支付页面: " + pageUrl);
    }
    else
    {
        Console.WriteLine("错误码: " + payResponse.Err_Code);
        Console.WriteLine("错误描述: " + payResponse.Err_Code_Des);
    }
}

// 调试信息
Console.WriteLine("请求URL: " + payResponse.RequestUrl);
Console.WriteLine("请求数据: " + payResponse.RequestData);
Console.WriteLine("响应数据: " + payResponse.ResponseData);

```

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

### Utility Class - HeemoneyUtils

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Provides utility functions for timestamp generation and request signing. These are typically called internally by the SDK but can be used manually when needed. The `GetSign` method requires parameters to be sorted by key before signing.

```csharp
using Heemoney;
using System;
using System.Collections.Generic;

// 获取Unix时间戳（毫秒）
long timestamp = HeemoneyUtils.GetTimeStamp(DateTime.Now);
Console.WriteLine("当前时间戳: " + timestamp);
// 输出: 当前时间戳: 1702627852000

// 手动生成签名（通常由SDK自动处理）
Dictionary<string, object> parameters = new Dictionary<string, object>
{
    { "app_id", "your_app_id" },
    { "mch_id", "your_mch_id" },
    { "out_trade_no", "20231215143052" },
    { "timestamp", timestamp.ToString() }
};

string sign = HeemoneyUtils.GetSign(parameters, HeemoneyConfig.KEY);
Console.WriteLine("签名: " + sign);
// 签名规则：按参数名ASCII排序拼接，末尾加key，MD5加密后转大写

// 组织完整请求数据（自动添加签名）
string jsonData = "{\"app_id\":\"your_app_id\",\"mch_id\":\"your_mch_id\"}";
string requestData = HeemoneyUtils.GetRequestData(jsonData);
Console.WriteLine("带签名的请求数据: " + requestData);

```

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

### Utility Class - HeemoneyUtils

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

SDK-provided utility class for generating timestamps and request signatures. Typically called internally by the SDK, but can be used manually when needed.

```APIDOC
## Utility Functions

### Description
Provides utility functions for common tasks like generating timestamps and signing requests.

### Functions
#### GetTimeStamp
Generates a Unix timestamp in milliseconds.

- **Input**: `DateTime` object.
- **Output**: `long` representing the timestamp.

#### GetSign
Manually generates a signature for request parameters.

- **Input**: `Dictionary<string, object>` of parameters, `string` API key.
- **Output**: `string` representing the signature.
- **Note**: Parameters are sorted by ASCII name, appended with the key, and then MD5 encrypted. The result is converted to uppercase.

#### GetRequestData
Organizes and signs JSON data for a request.

- **Input**: `string` JSON data.
- **Output**: `string` containing the JSON data with signature appended.

### Usage Example
```csharp
using Heemoney;
using System;
using System.Collections.Generic;

// Get Unix timestamp (milliseconds)
long timestamp = HeemoneyUtils.GetTimeStamp(DateTime.Now);
Console.WriteLine("Current Timestamp: " + timestamp);

// Manually generate signature (usually handled by SDK)
Dictionary<string, object> parameters = new Dictionary<string, object>
{
    { "app_id", "your_app_id" },
    { "mch_id", "your_mch_id" },
    { "out_trade_no", "20231215143052" },
    { "timestamp", timestamp.ToString() }
};

string sign = HeemoneyUtils.GetSign(parameters, HeemoneyConfig.KEY);
Console.WriteLine("Signature: " + sign);

// Organize complete request data (automatically adds signature)
string jsonData = "{\"app_id\":\"your_app_id\",\"mch_id\":\"your_mch_id\"}";
string requestData = HeemoneyUtils.GetRequestData(jsonData);
Console.WriteLine("Signed Request Data: " + requestData);
```
```

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

### Configure Merchant Information with HeemoneyConfig

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Configure essential merchant details such as App ID, Merchant ID, and API Key within the HeemoneyConfig class. These settings are crucial for all payment requests.

```csharp
using Heemoney;

// HeemoneyConfig.cs 中配置商户信息
public class HeemoneyConfig
{
    // 汇收银应用ID
    public const string APP_ID = "your_app_id";

    // 汇收银商户号
    public const string MCH_ID = "your_mch_id";

    // 汇收银支付密钥
    public const string KEY = "your_secret_key";

    // API主机地址
    public const string Host = "https://api.heemoney.com";

    // API版本
    public const string Version = "/api/v1";

    // API端点
    public const string PAY_URL = "/pay";
    public const string PAY_Test_URL = "/test";
    public const string Query_URL = "/query";
    public const string Refund_URL = "/refund";

    // 请求超时时间（毫秒）
    public const int TIME_OUT = 60000;
}
```

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

### Query Order Status - Heemoney.Query()

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Use this to query the payment status and details of an order using the merchant order number. This is useful for confirming transaction results after payment or for periodically synchronizing order statuses.

```csharp
using Heemoney;
using Heemoney.Models.Query;

// 创建查询请求
QueryRequest queryRequest = new QueryRequest();

// 基础配置
queryRequest.Version = "1";
queryRequest.App_ID = HeemoneyConfig.APP_ID;
queryRequest.Mch_Id = HeemoneyConfig.MCH_ID;
queryRequest.Charset = "gb2312";
queryRequest.Sign_Type = "MD5";
queryRequest.TimeStamp = HeemoneyUtils.GetTimeStamp(DateTime.Now).ToString();

// 要查询的订单号
queryRequest.OutTradeNo = "20231215143052";  // 商户订单号

// 发起查询请求
QueryResponse queryResponse = Heemoney.Heemoney.Query(queryRequest);

// 处理响应
if (queryResponse != null && queryResponse.Return_Code == "SUCCESS")
{
    if (queryResponse.Err_Code == "E0000")
    {
        // 查询成功
        Console.WriteLine("商户订单号: " + queryResponse.Out_Trade_No);
        Console.WriteLine("汇收银订单号: " + queryResponse.Hy_Bill_No);
        Console.WriteLine("支付渠道: " + queryResponse.Channel_Provider);
        Console.WriteLine("支付方式: " + queryResponse.Channel_Code);
        Console.WriteLine("商品名称: " + queryResponse.Subject);
        Console.WriteLine("货币类型: " + queryResponse.Currency);
        Console.WriteLine("订单金额: " + queryResponse.Total_Amt_Fen + " 分");
        Console.WriteLine("交易状态: " + queryResponse.Trade_Status);
        Console.WriteLine("处理时间: " + queryResponse.Hy_Deal_Time);

        // 交易状态判断
        switch (queryResponse.Trade_Status)
        {
            case "SUCCESS":
                Console.WriteLine("订单已支付成功");
                break;
            case "WAIT_BUYER_PAY":
                Console.WriteLine("等待用户支付");
                break;
            case "CLOSED":
                Console.WriteLine("订单已关闭");
                break;
        }
    }
    else
    {
        Console.WriteLine("查询失败: " + queryResponse.Err_Code_Des);
    }
}

```

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

### Refund Application API

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Apply for a refund for a successfully paid order. Supports full and partial refunds. Refund results are returned via asynchronous notifications.

```APIDOC
## POST /api/refund

### Description
Initiates a refund request for a previously paid order. Supports full or partial refunds.

### Method
POST

### Endpoint
/api/refund

### Parameters
#### Request Body
- **Version** (string) - Required - API version number.
- **App_ID** (string) - Required - Your application ID.
- **Mch_Id** (string) - Required - Your merchant ID.
- **Charset** (string) - Required - Character encoding, typically 'gb2312'.
- **Sign_Type** (string) - Required - Signature type, typically 'MD5'.
- **TimeStamp** (string) - Required - Current timestamp.
- **Out_Trade_No** (string) - Required - The original merchant order number.
- **Out_Refund_No** (string) - Required - The merchant's unique refund order number.
- **Channel_Provider** (string) - Required - The original payment channel.
- **Currency** (string) - Required - Currency type (e.g., 'CNY').
- **Total_Amt_Fen** (string) - Required - The total amount of the original order in cents.
- **Bill_TimeOut** (string) - Required - The amount to be refunded in cents.
- **Subject** (string) - Optional - Refund notification URL.
- **Merch_Extra** (string) - Optional - Extended parameters.

### Request Example
```json
{
  "Version": "1",
  "App_ID": "your_app_id",
  "Mch_Id": "your_mch_id",
  "Charset": "gb2312",
  "Sign_Type": "MD5",
  "TimeStamp": "1702627852000",
  "Out_Trade_No": "20231215143052",
  "Out_Refund_No": "R20231215143052",
  "Channel_Provider": "WeiXin",
  "Currency": "CNY",
  "Total_Amt_Fen": "100",
  "Bill_TimeOut": "100",
  "Subject": "https://www.example.com/refund_notify"
}
```

### Response
#### Success Response (200)
- **Return_Code** (string) - Indicates if the request was successful ('SUCCESS' or 'FAIL').
- **Err_Code** (string) - Error code if Return_Code is 'FAIL' or for specific business errors ('E0000' for success).
- **Err_Code_Des** (string) - Description of the error.
- **Out_Trade_No** (string) - Merchant order number.
- **Out_Refund_No** (string) - Merchant refund order number.
- **Hy_Bill_No** (string) - Heemoney order number.
- **Refund_Status** (string) - Current refund status (e.g., 'SUCCESS', 'PROCESSING', 'FAIL').
- **Refund_Msg** (string) - Refund details or error message.
- **Deal_Time** (string) - Processing time.

#### Response Example
```json
{
  "Return_Code": "SUCCESS",
  "Err_Code": "E0000",
  "Out_Trade_No": "20231215143052",
  "Out_Refund_No": "R20231215143052",
  "Hy_Bill_No": "HX20231215143052001",
  "Refund_Status": "PROCESSING",
  "Refund_Msg": "Refund is being processed.",
  "Deal_Time": "2023-12-15 15:00:00"
}
```
```

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

### Handle Heemoney SDK Exceptions

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Use a try-catch block to capture HeemoneyException for SDK-specific errors, general exceptions for system issues, and to process successful or business-level errors from the PayResponse.

```csharp
using Heemoney;
using Heemoney.Models.Pay;

try
{
    PayRequest payRequest = new PayRequest();
    // ... 设置请求参数

    PayResponse payResponse = Heemoney.Heemoney.Pay(payRequest);

    if (payResponse.Return_Code == "SUCCESS" && payResponse.Err_Code == "E0000")
    {
        // 处理成功响应
    }
    else
    {
        // 业务错误处理
        Console.WriteLine("业务错误: " + payResponse.Err_Code_Des);
    }
}
catch (HeemoneyException ex)
{
    // SDK内部错误
    Console.WriteLine("SDK错误: " + ex.Message);
}
catch (Exception ex)
{
    // 网络或其他系统错误
    Console.WriteLine("系统错误: " + ex.Message);
}
```

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

### Order Query API

Source: https://context7.com/heemoney/heemoney-csharp/llms.txt

Query the payment status and details of an order using the merchant order number. This is useful for confirming transaction results after payment or for periodically synchronizing order statuses.

```APIDOC
## POST /api/query

### Description
Queries the payment status and details of an order using the merchant order number.

### Method
POST

### Endpoint
/api/query

### Parameters
#### Request Body
- **Version** (string) - Required - API version number.
- **App_ID** (string) - Required - Your application ID.
- **Mch_Id** (string) - Required - Your merchant ID.
- **Charset** (string) - Required - Character encoding, typically 'gb2312'.
- **Sign_Type** (string) - Required - Signature type, typically 'MD5'.
- **TimeStamp** (string) - Required - Current timestamp.
- **OutTradeNo** (string) - Required - The merchant's order number.

### Request Example
```json
{
  "Version": "1",
  "App_ID": "your_app_id",
  "Mch_Id": "your_mch_id",
  "Charset": "gb2312",
  "Sign_Type": "MD5",
  "TimeStamp": "1702627852000",
  "OutTradeNo": "20231215143052"
}
```

### Response
#### Success Response (200)
- **Return_Code** (string) - Indicates if the request was successful ('SUCCESS' or 'FAIL').
- **Err_Code** (string) - Error code if Return_Code is 'FAIL' or for specific business errors ('E0000' for success).
- **Err_Code_Des** (string) - Description of the error.
- **Out_Trade_No** (string) - Merchant order number.
- **Hy_Bill_No** (string) - Heemoney order number.
- **Channel_Provider** (string) - Payment channel provider.
- **Channel_Code** (string) - Payment method code.
- **Subject** (string) - Product name.
- **Currency** (string) - Currency type.
- **Total_Amt_Fen** (string) - Total order amount in cents.
- **Trade_Status** (string) - Current transaction status (e.g., 'SUCCESS', 'WAIT_BUYER_PAY', 'CLOSED').
- **Hy_Deal_Time** (string) - Transaction processing time.

#### Response Example
```json
{
  "Return_Code": "SUCCESS",
  "Err_Code": "E0000",
  "Out_Trade_No": "20231215143052",
  "Hy_Bill_No": "HX20231215143052001",
  "Channel_Provider": "WeiXin",
  "Channel_Code": "JSAPI",
  "Subject": "Test Product",
  "Currency": "CNY",
  "Total_Amt_Fen": "100",
  "Trade_Status": "SUCCESS",
  "Hy_Deal_Time": "2023-12-15 14:35:00"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.