README

English | 中文

WeChat Pay integration for Symfony applications, providing payment order management, refund processing, and automated bill synchronization.

Features
Installation
Configuration
Console Commands
Entities
Services
Usage Example
Advanced Usage
Development Guide
Dependencies
Contributing
License

Features

WeChat Pay order creation and management
Refund order processing
Automated bill downloading
Order status synchronization
Multi-merchant support
Payment callback handling

Installation

composer require tourze/wechat-pay-bundle

Configuration

// config/bundles.php
return [
    // ...
    WechatPayBundle\WechatPayBundle::class => ['all' => true],
];

Console Commands

Download Fund Flow Bill

php bin/console wechat:pay:download-fund-flow-bill

Downloads WeChat Pay fund flow bills. Runs automatically at 10:00 and 11:00 daily, fetching the last 7 days of fund statements.

Download Trade Bill

php bin/console wechat:pay:download-trade-bill

Downloads WeChat Pay trade bills. Runs automatically at 10:00 and 11:00 daily, fetching the last 7 days of transaction records.

Check Order Expiration

php bin/console wechat:pay:check-order-expire

Checks and updates expired payment orders. Runs every minute to query orders that have expired but are still in INIT status.

Check Refund Status

php bin/console wechat:refund:check-order-status

Checks and updates refund order status. Runs every minute to query refunds in PROCESSING status and update their actual status.

Entities

PayOrder - Payment order entity with order management
RefundOrder - Refund order entity with goods detail support
RefundGoodsDetail - Refund goods detail entity
Merchant - Merchant configuration entity
TradeBill - Trade bill record entity
FundFlowBill - Fund flow bill record entity

Enums

PayOrderStatus - Payment order status enumeration
AccountType - WeChat Pay account type enumeration
BillType - Bill type enumeration

Services

UnifiedOrder - Creates payment orders for various trade types
WechatAppPayService - Handles APP payment order creation
WechatJsApiPayService - Handles JSAPI payment order creation
WechatPayBuilder - Builds WeChat Pay API clients
AttributeControllerLoader - Loads controller attributes for routing

Usage Example

// Create a payment order
$params = new AppOrderParams();
$params->setMchId('your_merchant_id');
$params->setAppId('your_app_id');
// ... set other parameters
$payOrder = $unifiedOrder->createAppOrder($params);

// Refund processing is handled automatically via RefundOrder entity
$refundOrder = new RefundOrder();
$refundOrder->setPayOrder($payOrder);
$refundOrder->setMoney($amount);
$refundOrder->setReason($reason);
$entityManager->persist($refundOrder);
$entityManager->flush(); // This triggers the refund via RefundOrderListener

Advanced Usage

Custom Payment Processing

use WechatPayBundle\Service\UnifiedOrder;
use WechatPayBundle\Request\AppOrderParams;

class CustomPaymentService
{
    public function __construct(private UnifiedOrder $unifiedOrder) {}
    
    public function processCustomPayment(array $orderData): array
    {
        $params = new AppOrderParams();
        $params->setMchId($orderData['merchant_id']);
        $params->setAppId($orderData['app_id']);
        $params->setContractId($orderData['order_id']);
        $params->setDescription($orderData['description']);
        $params->setMoney($orderData['amount']);
        
        return $this->unifiedOrder->createAppOrder($params);
    }
}

Handling Payment Callbacks

use WechatPayBundle\Entity\PayOrder;
use WechatPayBundle\Enum\PayOrderStatus;

class PaymentCallbackHandler
{
    public function handleCallback(array $callbackData): void
    {
        $orderId = $callbackData['out_trade_no'];
        $payOrder = $this->findPayOrder($orderId);
        
        if ($callbackData['result_code'] === 'SUCCESS') {
            $payOrder->setStatus(PayOrderStatus::SUCCESS);
            $payOrder->setPayTime(new \DateTime());
        } else {
            $payOrder->setStatus(PayOrderStatus::FAIL);
        }
        
        $this->entityManager->flush();
    }
}

Multi-Merchant Configuration

use WechatPayBundle\Entity\Merchant;

class MerchantService
{
    public function configureMerchant(string $mchId, string $pemKey): Merchant
    {
        $merchant = new Merchant();
        $merchant->setMchId($mchId);
        $merchant->setPemKey($pemKey);
        $merchant->setIsActive(true);
        
        $this->entityManager->persist($merchant);
        $this->entityManager->flush();
        
        return $merchant;
    }
}

Development Guide

Database Migrations

Use Doctrine migrations to manage database schema:

php bin/console doctrine:migrations:migrate

Testing

Run unit tests:

./vendor/bin/phpunit packages/wechat-pay-bundle/tests

Events

This bundle provides the following events:

AppPayCallbackSuccessEvent - Triggered after successful APP payment callback
JSAPIPayCallbackSuccessEvent - Triggered after successful JSAPI payment callback
NativePayCallbackSuccessEvent - Triggered after successful Native payment callback

Entity Listeners

PayOrderListener - Handles payment order lifecycle events
RefundOrderListener - Handles refund order lifecycle events

Dependencies

This bundle requires the following packages:

Core Dependencies

php: ^8.1
symfony/framework-bundle: ^7.3
doctrine/orm: ^3.0
wechatpay/wechatpay: ^1.4
nesbot/carbon: ^2.72 || ^3
league/flysystem: ^3.10
yiisoft/json: ^1.0
yiisoft/arrays: ^3

Tourze Internal Dependencies

tourze/doctrine-snowflake-bundle: 0.1.*
tourze/symfony-snowflake-bundle: 0.0.*
tourze/http-client-bundle: 0.1.*
tourze/symfony-cron-job-bundle: 0.1.*
tourze/doctrine-timestamp-bundle: 0.0.*
tourze/doctrine-track-bundle: 0.1.*
tourze/enum-extra: 0.1.*
tourze/file-storage-bundle: 0.0.*
tourze/xml-helper: 0.0.*

Contributing

We welcome Pull Requests and Issues. Please ensure:

Follow PSR-12 coding standards
Add appropriate unit tests
Update relevant documentation

License

This bundle is part of the Tourze monorepo project.

tourze / wechat-pay-bundle

Maintainers

Details