CtrlK
BlogDocsLog inGet started
Tessl Logo

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

core-payment.mddocs/

Core Payment Operations

Essential payment processing functionality including order creation, querying, and cancellation. Supports all major WeChat Pay payment methods with both v2 and v3 API protocols.

Capabilities

Unified Order Creation (API v2)

Creates payment orders using WeChat Pay API v2 (XML-based). Supports all trade types including JSAPI, NATIVE, APP, and MWEB.

/**
 * Creates a unified payment order using WeChat Pay API v2
 * @param request Order creation request with payment details
 * @return Order creation result with payment parameters
 * @throws WxPayException if order creation fails
 */
WxPayUnifiedOrderResult unifiedOrder(WxPayUnifiedOrderRequest request) throws WxPayException;

Usage Example:

import com.github.binarywang.wxpay.bean.request.WxPayUnifiedOrderRequest;
import com.github.binarywang.wxpay.bean.result.WxPayUnifiedOrderResult;
import com.github.binarywang.wxpay.constant.WxPayConstants;

// Create unified order request
WxPayUnifiedOrderRequest request = WxPayUnifiedOrderRequest.newBuilder()
    .outTradeNo("ORDER_20230101_001")
    .totalFee(100) // Amount in cents (1.00 CNY)
    .body("Test Product Purchase")
    .tradeType(WxPayConstants.TradeType.JSAPI)
    .openid("user-openid-for-jsapi-payment")
    .notifyUrl("https://your-domain.com/payment/notify")
    .spbillCreateIp("192.168.1.1")
    .build();

// Execute order creation
WxPayUnifiedOrderResult result = wxPayService.unifiedOrder(request);

// Extract payment parameters for frontend
String prepayId = result.getPrepayId();
Map<String, String> payParams = result.getPayInfo();

Unified Order Creation (API v3)

Creates payment orders using WeChat Pay API v3 (JSON-based) with enhanced security and additional features.

/**
 * Creates a unified payment order using WeChat Pay API v3
 * @param tradeType Payment method type (JSAPI, NATIVE, APP, MWEB)
 * @param request Order creation request with payment details
 * @return Order creation result with payment parameters
 * @throws WxPayException if order creation fails
 */
WxPayUnifiedOrderV3Result unifiedOrderV3(TradeTypeEnum tradeType, WxPayUnifiedOrderV3Request request) throws WxPayException;

Usage Example:

import com.github.binarywang.wxpay.bean.request.WxPayUnifiedOrderV3Request;
import com.github.binarywang.wxpay.bean.result.WxPayUnifiedOrderV3Result;
import com.github.binarywang.wxpay.bean.result.enums.TradeTypeEnum;

// Create V3 order request
WxPayUnifiedOrderV3Request request = new WxPayUnifiedOrderV3Request();
request.setOutTradeNo("ORDER_20230101_002");
request.setDescription("Premium Product Purchase");
request.setNotifyUrl("https://your-domain.com/payment/notify/v3");

// Set amount details
WxPayUnifiedOrderV3Request.Amount amount = new WxPayUnifiedOrderV3Request.Amount();
amount.setTotal(100); // Amount in cents
amount.setCurrency("CNY");
request.setAmount(amount);

// Set payer info for JSAPI
WxPayUnifiedOrderV3Request.Payer payer = new WxPayUnifiedOrderV3Request.Payer();
payer.setOpenid("user-openid-for-jsapi");
request.setPayer(payer);

// Execute V3 order creation
WxPayUnifiedOrderV3Result result = wxPayService.unifiedOrderV3(TradeTypeEnum.JSAPI, request);

// Extract payment parameters
String prepayId = result.getPrepayId();
Map<String, String> payParams = result.getPayInfo();

Order Querying

Query payment order status and details using either transaction ID or merchant order number.

/**
 * Query payment order by transaction ID or merchant order number
 * @param transactionId WeChat transaction ID (optional if outTradeNo provided)
 * @param outTradeNo Merchant order number (optional if transactionId provided)
 * @return Order query result with payment status and details
 * @throws WxPayException if query fails
 */
WxPayOrderQueryResult queryOrder(String transactionId, String outTradeNo) throws WxPayException;

/**
 * Query payment order using request object
 * @param request Order query request with search parameters
 * @return Order query result with payment status and details
 * @throws WxPayException if query fails
 */
WxPayOrderQueryResult queryOrder(WxPayOrderQueryRequest request) throws WxPayException;

Usage Example:

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

// Query by merchant order number
WxPayOrderQueryResult result = wxPayService.queryOrder(null, "ORDER_20230101_001");

// Check payment status
if ("SUCCESS".equals(result.getTradeState())) {
    System.out.println("Payment successful");
    System.out.println("Transaction ID: " + result.getTransactionId());
    System.out.println("Total Fee: " + result.getTotalFee());
    System.out.println("Payment Time: " + result.getTimeEnd());
} else {
    System.out.println("Payment status: " + result.getTradeState());
}

Order Querying (API v3)

Query payment orders using WeChat Pay API v3 with enhanced response data.

/**
 * Query payment order using WeChat Pay API v3
 * @param request V3 order query request
 * @return V3 order query result with detailed payment information
 * @throws WxPayException if query fails
 */
WxPayOrderQueryV3Result queryOrderV3(WxPayOrderQueryV3Request request) throws WxPayException;

Order Closing

Close unpaid orders to prevent future payment attempts.

/**
 * Close an unpaid order
 * @param outTradeNo Merchant order number to close
 * @return Order close result
 * @throws WxPayException if close operation fails
 */
WxPayOrderCloseResult closeOrder(String outTradeNo) throws WxPayException;

/**
 * Close an unpaid order using request object
 * @param request Order close request
 * @return Order close result
 * @throws WxPayException if close operation fails
 */
WxPayOrderCloseResult closeOrder(WxPayOrderCloseRequest request) throws WxPayException;

Usage Example:

// Close order by merchant order number
WxPayOrderCloseResult result = wxPayService.closeOrder("ORDER_20230101_001");

if ("SUCCESS".equals(result.getResultCode())) {
    System.out.println("Order closed successfully");
}

Order Closing (API v3)

Close orders using WeChat Pay API v3. Note that v3 close operations do not return result objects.

/**
 * Close an unpaid order using WeChat Pay API v3
 * @param outTradeNo Merchant order number to close
 * @throws WxPayException if close operation fails
 */
void closeOrderV3(String outTradeNo) throws WxPayException;

/**
 * Close an unpaid order using WeChat Pay API v3
 * @param request V3 order close request
 * @throws WxPayException if close operation fails
 */
void closeOrderV3(WxPayOrderCloseV3Request request) throws WxPayException;

/**
 * Close partner order using WeChat Pay API v3 (for service providers)
 * @param outTradeNo Merchant order number to close
 * @throws WxPayException if close operation fails
 */
void closePartnerOrderV3(String outTradeNo) throws WxPayException;

/**
 * Close partner order using WeChat Pay API v3 (for service providers)
 * @param request Partner order close request
 * @throws WxPayException if close operation fails
 */
void closePartnerOrderV3(WxPayPartnerOrderCloseV3Request request) throws WxPayException;

Micropay (Barcode/QR Code Scanning)

Process payments using barcode or QR code scanning, where customers present their payment code to merchants.

/**
 * Process micropay (barcode/QR scanning) payment
 * @param request Micropay request with auth code and payment details
 * @return Micropay result with payment status
 * @throws WxPayException if payment processing fails
 */
WxPayMicropayResult micropay(WxPayMicropayRequest request) throws WxPayException;

/**
 * Process codepay payment (alternative micropay method)
 * @param request Codepay request with payment details
 * @return Codepay result with payment status
 * @throws WxPayException if payment processing fails
 */
WxPayCodepayResult codepay(WxPayCodepayRequest request) throws WxPayException;

Usage Example:

import com.github.binarywang.wxpay.bean.request.WxPayMicropayRequest;
import com.github.binarywang.wxpay.bean.result.WxPayMicropayResult;

// Create micropay request
WxPayMicropayRequest request = WxPayMicropayRequest.newBuilder()
    .outTradeNo("SCAN_ORDER_20230101_001")
    .totalFee(100) // Amount in cents
    .body("Scanned Product Purchase")
    .authCode("134567890123456789") // Customer's payment code
    .spbillCreateIp("192.168.1.1")
    .build();

// Process micropay
WxPayMicropayResult result = wxPayService.micropay(request);

// Check payment result
if ("SUCCESS".equals(result.getResultCode())) {
    System.out.println("Payment successful: " + result.getTransactionId());
} else if ("USERPAYING".equals(result.getErrCode())) {
    System.out.println("User is paying, please wait and query order status");
} else {
    System.out.println("Payment failed: " + result.getErrCodeDes());
}

Order Reversal

Reverse or cancel orders, primarily used for barcode payment scenarios.

/**
 * Reverse/cancel an order (API v2)
 * @param request Order reverse request
 * @return Order reverse result
 * @throws WxPayException if reverse operation fails
 */
WxPayOrderReverseResult reverseOrder(WxPayOrderReverseRequest request) throws WxPayException;

/**
 * Reverse/cancel an order (API v3)
 * @param request V3 order reverse request
 * @return V3 order reverse result
 * @throws WxPayException if reverse operation fails
 */
WxPayOrderReverseV3Result reverseOrderV3(WxPayOrderReverseV3Request request) throws WxPayException;

/**
 * Reverse/cancel an order by merchant order number (API v3)
 * @param outTradeNo Merchant order number to reverse
 * @return V3 order reverse result
 * @throws WxPayException if reverse operation fails
 */
WxPayOrderReverseV3Result reverseOrderV3(String outTradeNo) throws WxPayException;

Request Types

WxPayUnifiedOrderRequest (API v2)

class WxPayUnifiedOrderRequest extends BaseWxPayRequest {
    // Required fields
    String outTradeNo;        // Merchant order number
    Integer totalFee;         // Payment amount in cents
    String body;              // Product description
    String tradeType;         // Payment type (JSAPI, NATIVE, APP, MWEB)
    String notifyUrl;         // Notification callback URL
    String spbillCreateIp;    // Client IP address
    
    // Conditional fields
    String openid;            // Required for JSAPI payments
    String productId;         // Required for NATIVE payments
    
    // Optional fields
    String detail;            // Product detail description
    String attach;            // Additional data
    String feeType;           // Currency type (default: CNY)
    String timeStart;         // Payment start time
    String timeExpire;        // Payment expiration time
    String goodsTag;          // Product tag
    
    // Builder pattern
    static WxPayUnifiedOrderRequestBuilder newBuilder();
}

WxPayUnifiedOrderV3Request (API v3)

class WxPayUnifiedOrderV3Request {
    String outTradeNo;        // Merchant order number
    String description;       // Product description
    String notifyUrl;         // Notification callback URL
    Amount amount;            // Payment amount details
    Payer payer;              // Payer information (for JSAPI)
    
    // Amount details
    static class Amount {
        Integer total;        // Total amount in cents
        String currency;      // Currency code (CNY)
    }
    
    // Payer information
    static class Payer {
        String openid;        // User openid for JSAPI payments
    }
}

Result Types

WxPayUnifiedOrderResult (API v2)

class WxPayUnifiedOrderResult extends BaseWxPayResult {
    String prepayId;          // Prepayment ID
    String codeUrl;           // Payment QR code URL (for NATIVE)
    String mwebUrl;           // H5 payment URL (for MWEB)
    
    // Payment parameter generation
    Map<String, String> getPayInfo();
    WxPayAppOrderResult createAppOrder();
    WxPayMpOrderResult createMpOrder();
    WxPayNativeOrderResult createNativeOrder();
    WxPayH5OrderResult createH5Order();
}

WxPayOrderQueryResult

class WxPayOrderQueryResult extends BaseWxPayResult {
    String tradeState;        // Payment status (SUCCESS, REFUND, etc.)
    String transactionId;     // WeChat transaction ID
    String outTradeNo;        // Merchant order number
    Integer totalFee;         // Payment amount in cents
    String timeEnd;           // Payment completion time
    String tradeStateDesc;    // Payment status description
    String bankType;          // Bank type
    String feeType;           // Currency type
}

Utility Methods

Additional utility methods for URL shortening, authentication, and QR code generation.

/**
 * Shorten a long URL for WeChat Pay
 * @param longUrl Long URL to shorten
 * @return Shortened URL
 * @throws WxPayException if URL shortening fails
 */
String shorturl(String longUrl) throws WxPayException;

/**
 * Shorten URL using request object
 * @param request URL shortening request
 * @return Shortened URL
 * @throws WxPayException if URL shortening fails
 */
String shorturl(WxPayShorturlRequest request) throws WxPayException;

/**
 * Convert auth code to openid
 * @param authCode Authorization code from customer
 * @return User's openid
 * @throws WxPayException if conversion fails
 */
String authcode2Openid(String authCode) throws WxPayException;

/**
 * Convert auth code to openid using request object
 * @param request Auth code conversion request
 * @return User's openid
 * @throws WxPayException if conversion fails
 */
String authcode2Openid(WxPayAuthcode2OpenidRequest request) throws WxPayException;

Usage Example:

// Shorten a payment URL
String longUrl = "https://pay.weixin.qq.com/wxpay/pay.action?prepay_id=wx20230101123456";
String shortUrl = wxPayService.shorturl(longUrl);

// Convert auth code to openid for user identification
String authCode = "134567890123456789"; // From customer scan
String openid = wxPayService.authcode2Openid(authCode);

QR Code Generation

Generate QR codes for scan-and-pay scenarios.

/**
 * Create QR code for scan pay mode 1 (customer scans merchant QR)
 * @param productId Product identifier
 * @return QR code content string
 */
String createScanPayQrcodeMode1(String productId);

/**
 * Create QR code image for scan pay mode 1 with logo
 * @param productId Product identifier
 * @param logoFile Logo image file to embed
 * @param sideLength QR code size in pixels
 * @return QR code image as byte array
 * @throws Exception if QR code generation fails
 */
byte[] createScanPayQrcodeMode1(String productId, File logoFile, Integer sideLength) throws Exception;

/**
 * Create QR code image for scan pay mode 2 (merchant scans customer QR)
 * @param codeUrl Code URL from unified order result
 * @param logoFile Logo image file to embed
 * @param sideLength QR code size in pixels
 * @return QR code image as byte array
 * @throws Exception if QR code generation fails
 */
byte[] createScanPayQrcodeMode2(String codeUrl, File logoFile, Integer sideLength) throws Exception;

Common Payment Statuses

  • SUCCESS: Payment successful
  • REFUND: Order refunded
  • NOTPAY: Order created but not paid
  • CLOSED: Order closed
  • REVOKED: Order revoked (barcode payment)
  • USERPAYING: User paying (barcode payment)
  • PAYERROR: Payment failed

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