tessl/maven-com-github-binarywang--weixin-java-pay

Comprehensive Java SDK for integrating with WeChat Pay services including unified orders, refunds, enterprise payments, red packets, profit sharing, and marketing services

—

Pending

Overview

Eval results

Files

Refund Management

Name: tessl/maven-com-github-binarywang--weixin-java-pay
Author: tessl

Comprehensive refund processing with support for full and partial refunds, refund querying, and notification handling for both API versions.

Capabilities

Create Refund (API v2)

Process refunds using WeChat Pay API v2 with XML-based communication.

/**
 * Create a refund using WeChat Pay API v2
 * @param request Refund request with transaction and refund details
 * @return Refund result with refund ID and status
 * @throws WxPayException if refund processing fails
 */
WxPayRefundResult refund(WxPayRefundRequest request) throws WxPayException;

/**
 * Create a refund using WeChat Pay API v2 (alternative method)
 * @param request Refund request with transaction and refund details
 * @return Refund result with refund ID and status
 * @throws WxPayException if refund processing fails
 */
WxPayRefundResult refundV2(WxPayRefundRequest request) throws WxPayException;

Usage Example:

import com.github.binarywang.wxpay.bean.request.WxPayRefundRequest;
import com.github.binarywang.wxpay.bean.result.WxPayRefundResult;

// Create refund request
WxPayRefundRequest refundRequest = WxPayRefundRequest.newBuilder()
    .transactionId("1234567890123456789") // WeChat transaction ID
    .outRefundNo("REFUND_20230101_001")   // Merchant refund number
    .totalFee(100)                        // Original payment amount in cents
    .refundFee(50)                        // Refund amount in cents (partial refund)
    .refundDesc("Product defect")         // Refund reason
    .notifyUrl("https://your-domain.com/refund/notify")
    .build();

// Alternatively, use merchant order number instead of transaction ID
WxPayRefundRequest refundRequest2 = WxPayRefundRequest.newBuilder()
    .outTradeNo("ORDER_20230101_001")     // Merchant order number
    .outRefundNo("REFUND_20230101_002")
    .totalFee(100)
    .refundFee(100)                       // Full refund
    .refundDesc("Customer cancellation")
    .build();

// Process refund
WxPayRefundResult result = wxPayService.refund(refundRequest);

if ("SUCCESS".equals(result.getResultCode())) {
    System.out.println("Refund successful");
    System.out.println("Refund ID: " + result.getRefundId());
    System.out.println("Refund Fee: " + result.getRefundFee());
}

Create Refund (API v3)

Process refunds using WeChat Pay API v3 with JSON-based communication and enhanced security.

/**
 * Create a refund using WeChat Pay API v3
 * @param request V3 refund request with transaction and refund details
 * @return V3 refund result with detailed refund information
 * @throws WxPayException if refund processing fails
 */
WxPayRefundV3Result refundV3(WxPayRefundV3Request request) throws WxPayException;

Usage Example:

import com.github.binarywang.wxpay.bean.request.WxPayRefundV3Request;
import com.github.binarywang.wxpay.bean.result.WxPayRefundV3Result;

// Create V3 refund request
WxPayRefundV3Request refundRequest = new WxPayRefundV3Request();
refundRequest.setOutRefundNo("REFUND_20230101_003");
refundRequest.setReason("Quality issue");
refundRequest.setNotifyUrl("https://your-domain.com/refund/notify/v3");

// Set amount details
WxPayRefundV3Request.Amount amount = new WxPayRefundV3Request.Amount();
amount.setRefund(50);    // Refund amount in cents
amount.setTotal(100);    // Original payment amount in cents
amount.setCurrency("CNY");
refundRequest.setAmount(amount);

// Set transaction reference (use either transactionId or outTradeNo)
refundRequest.setTransactionId("1234567890123456789");
// OR
// refundRequest.setOutTradeNo("ORDER_20230101_001");

// Process V3 refund
WxPayRefundV3Result result = wxPayService.refundV3(refundRequest);

System.out.println("Refund ID: " + result.getRefundId());
System.out.println("Status: " + result.getStatus());
System.out.println("Success Time: " + result.getSuccessTime());

Query Refund Status (API v2)

Query refund status and details using various identifiers.

/**
 * Query refund status using transaction or refund identifiers
 * @param transactionId WeChat transaction ID (optional)
 * @param outTradeNo Merchant order number (optional)
 * @param outRefundNo Merchant refund number (optional)
 * @param refundId WeChat refund ID (optional)
 * @return Refund query result with status and details
 * @throws WxPayException if query fails
 */
WxPayRefundQueryResult refundQuery(String transactionId, String outTradeNo, 
                                  String outRefundNo, String refundId) throws WxPayException;

/**
 * Query refund status using request object
 * @param request Refund query request
 * @return Refund query result with status and details
 * @throws WxPayException if query fails
 */
WxPayRefundQueryResult refundQuery(WxPayRefundQueryRequest request) throws WxPayException;

/**
 * Query refund status using WeChat Pay API v2 (alternative method)
 * @param request Refund query request
 * @return Refund query result with status and details
 * @throws WxPayException if query fails
 */
WxPayRefundQueryResult refundQueryV2(WxPayRefundQueryRequest request) throws WxPayException;

Usage Example:

import com.github.binarywang.wxpay.bean.result.WxPayRefundQueryResult;

// Query refund by merchant refund number
WxPayRefundQueryResult result = wxPayService.refundQuery(
    null, null, "REFUND_20230101_001", null);

// Check refund status
System.out.println("Refund Status: " + result.getRefundStatus());
System.out.println("Refund Count: " + result.getRefundCount());

// Process each refund in the result
for (int i = 0; i < result.getRefundCount(); i++) {
    System.out.println("Refund " + i + ":");
    System.out.println("  Refund ID: " + result.getRefundId(i));
    System.out.println("  Refund Fee: " + result.getRefundFee(i));
    System.out.println("  Status: " + result.getRefundStatus(i));
    System.out.println("  Success Time: " + result.getRefundSuccessTime(i));
}

Query Refund Status (API v3)

Query refund status using WeChat Pay API v3.

/**
 * Query refund status using merchant refund number (API v3)
 * @param outRefundNo Merchant refund number
 * @return V3 refund query result with detailed information
 * @throws WxPayException if query fails
 */
WxPayRefundQueryV3Result refundQueryV3(String outRefundNo) throws WxPayException;

/**
 * Query refund status using request object (API v3)
 * @param request V3 refund query request
 * @return V3 refund query result with detailed information
 * @throws WxPayException if query fails
 */
WxPayRefundQueryV3Result refundQueryV3(WxPayRefundQueryV3Request request) throws WxPayException;

/**
 * Query partner refund status (API v3)
 * @param request Partner refund query request
 * @return V3 refund query result with detailed information
 * @throws WxPayException if query fails
 */
WxPayRefundQueryV3Result refundPartnerQueryV3(WxPayRefundQueryV3Request request) throws WxPayException;

Usage Example:

import com.github.binarywang.wxpay.bean.result.WxPayRefundQueryV3Result;

// Query V3 refund by merchant refund number
WxPayRefundQueryV3Result result = wxPayService.refundQueryV3("REFUND_20230101_003");

System.out.println("Refund ID: " + result.getRefundId());
System.out.println("Status: " + result.getStatus());
System.out.println("Create Time: " + result.getCreateTime());
System.out.println("Success Time: " + result.getSuccessTime());

// Check amount details
WxPayRefundQueryV3Result.Amount amount = result.getAmount();
System.out.println("Refund Amount: " + amount.getRefund());
System.out.println("Total Amount: " + amount.getTotal());

Request Types

WxPayRefundRequest (API v2)

class WxPayRefundRequest extends BaseWxPayRequest {
    // Transaction reference (provide one)
    String transactionId;     // WeChat transaction ID
    String outTradeNo;        // Merchant order number
    
    // Required fields
    String outRefundNo;       // Merchant refund number (unique)
    Integer totalFee;         // Original payment amount in cents
    Integer refundFee;        // Refund amount in cents
    
    // Optional fields
    String refundFeeType;     // Refund currency (default: CNY)
    String refundDesc;        // Refund reason/description
    String refundAccount;     // Refund account source
    String notifyUrl;         // Refund notification URL
    
    // Builder pattern
    static WxPayRefundRequestBuilder newBuilder();
}

WxPayRefundV3Request (API v3)

class WxPayRefundV3Request {
    // Transaction reference (provide one)
    String transactionId;     // WeChat transaction ID
    String outTradeNo;        // Merchant order number
    
    // Required fields
    String outRefundNo;       // Merchant refund number (unique)
    String reason;            // Refund reason
    Amount amount;            // Amount details
    String notifyUrl;         // Refund notification URL
    
    // Amount details
    static class Amount {
        Integer refund;       // Refund amount in cents
        Integer total;        // Original payment amount in cents
        String currency;      // Currency code (CNY)
    }
}

WxPayRefundQueryRequest

class WxPayRefundQueryRequest extends BaseWxPayRequest {
    // Search criteria (provide at least one)
    String transactionId;     // WeChat transaction ID
    String outTradeNo;        // Merchant order number
    String outRefundNo;       // Merchant refund number
    String refundId;          // WeChat refund ID
    Integer offset;           // Query offset (for pagination)
}

Result Types

WxPayRefundResult (API v2)

class WxPayRefundResult extends BaseWxPayResult {
    String transactionId;     // WeChat transaction ID
    String outTradeNo;        // Merchant order number
    String outRefundNo;       // Merchant refund number
    String refundId;          // WeChat refund ID
    Integer refundFee;        // Refund amount in cents
    Integer settlementRefundFee; // Settlement refund amount
    Integer totalFee;         // Original payment amount in cents
    Integer settlementTotalFee;  // Settlement total amount
    String feeType;           // Currency type
    Integer cashFee;          // Cash payment amount
    String cashFeeType;       // Cash currency type
    Integer cashRefundFee;    // Cash refund amount
    Integer couponRefundFee;  // Coupon refund amount
    Integer couponRefundCount; // Coupon refund count
}

WxPayRefundV3Result (API v3)

class WxPayRefundV3Result {
    String refundId;          // WeChat refund ID
    String outRefundNo;       // Merchant refund number
    String transactionId;     // WeChat transaction ID
    String outTradeNo;        // Merchant order number
    String channel;           // Refund channel
    String userReceivedAccount; // User refund account
    String status;            // Refund status
    String createTime;        // Refund creation time
    String successTime;       // Refund success time
    Amount amount;            // Amount details
    
    static class Amount {
        Integer total;        // Original payment amount
        Integer refund;       // Refund amount
        Integer payerTotal;   // Payer amount
        Integer payerRefund;  // Payer refund amount
        Integer settlementRefund; // Settlement refund amount
        Integer settlementTotal;  // Settlement total amount
        Integer discountRefund;   // Discount refund amount
        String currency;      // Currency code
    }
}

WxPayRefundQueryResult (API v2)

class WxPayRefundQueryResult extends BaseWxPayResult {
    String transactionId;     // WeChat transaction ID
    String outTradeNo;        // Merchant order number
    Integer totalFee;         // Original payment amount
    Integer settlementTotalFee; // Settlement total amount
    String feeType;           // Currency type
    Integer cashFee;          // Cash payment amount
    Integer refundCount;      // Number of refunds
    
    // Methods to access refund details by index
    String getOutRefundNo(int index);
    String getRefundId(int index);
    String getRefundChannel(int index);
    Integer getRefundFee(int index);
    Integer getSettlementRefundFee(int index);
    Integer getCouponRefundFee(int index);
    Integer getCouponRefundCount(int index);
    String getRefundStatus(int index);
    String getRefundAccount(int index);
    String getRefundRecvAccount(int index);
    String getRefundSuccessTime(int index);
}

Refund Status Values

API v2 Status Values

SUCCESS: Refund successful
REFUNDCLOSE: Refund closed
PROCESSING: Refund processing
CHANGE: Refund abnormal

API v3 Status Values

SUCCESS: Refund successful
CLOSED: Refund closed
PROCESSING: Refund processing
ABNORMAL: Refund abnormal

Important Notes

Certificate Requirements

Refund operations require merchant certificates for authentication:

API v2: Requires .p12 certificate file configured in WxPayConfig.setKeyPath()
API v3: Requires private key and certificate serial number

Refund Limitations

Partial refunds are supported (refund amount can be less than total payment)
Multiple partial refunds are allowed for the same order
Refund amount cannot exceed the original payment amount
Refunds typically process within 1-7 business days depending on the original payment method

Notification Handling

Configure notification URLs to receive refund status updates:

API v2: XML-based notifications
API v3: JSON-based notifications with enhanced security

Error Handling

Common refund errors include:

ORDERNOTEXIST: Original order not found
NOTENOUGH: Insufficient refundable amount
FREQ_LIMIT: Refund frequency limit exceeded

Install with Tessl CLI

npx tessl i tessl/maven-com-github-binarywang--weixin-java-pay

docs

advanced-services.md

configuration-security.md

core-payment.md

enterprise-services.md

index.md

notification-processing.md

payment-methods.md

refund-management.md

tile.json

tessl/maven-com-github-binarywang--weixin-java-pay