Wechat Pay Score Bundle Laravel Package

Getting Started

Install the package with Composer and confirm Laravel package discovery:

composer require tourze/wechat-pay-score-bundle

If the package does not auto-register, add its service provider in config/app.php. Publish any package config (check the README for the exact tag) and move credentials into .env:

WECHAT_PAY_MCH_ID=
WECHAT_PAY_APP_ID=
WECHAT_PAY_SERIAL_NO=
WECHAT_PAY_PRIVATE_KEY_PATH=
WECHAT_PAY_API_V3_KEY=
WECHAT_PAY_PLATFORM_CERT_PATH=

Look first at:

1. README.md for the supported Laravel versions and the exposed facade/service name.
2. config/ for credential keys and HTTP client options.
3. src/ for the public service classes and DTOs.
4. The 0.0.1...0.1.0 diff, since the release notes only link to the changelog.
5. tests/ for sandbox or fake-gateway examples.

A sensible first use case is a sandbox WeChat Pay Score order: create a score service order, return the prepay parameters to the client, then query the order by out-trade number to confirm the package signs and parses responses correctly. Do not start with production credentials.

Implementation Patterns

Keep the package behind your own application service rather than injecting it directly into controllers. A typical flow:

• ScoreOrderService::create() builds your domain order, calls the package to create the WeChat Pay Score order, and stores the returned prepay ID.
• A controller returns only the client-side payment parameters, never merchant credentials.
• A webhook controller receives WeChat notifications, verifies the signature through the package, and dispatches a Laravel event or job.
• A queued listener updates your local order state idempotently.
• A scheduled command reconciles pending orders by querying WeChat Pay for stale or missing callbacks.

Use Laravel’s container and configuration system:

$score = app(WechatPayScore::class);

$result = $score->createOrder([
    'out_order_no' => $order->out_trade_no,
    'appid' => config('wechat-pay-score.app_id'),
    'mchid' => config('wechat-pay-score.mch_id'),
    'description' => $order->description,
    'amount' => ['total' => $order->total_cents],
]);

Wrap package exceptions in your own domain exceptions so controllers and jobs do not depend on the package’s exception hierarchy. Log the WeChat request-id / Wechatpay-Request-ID header on every call; it is the most useful value when debugging failed signatures or malformed requests.

For integration testing, prefer a contract test around your wrapper with a fake HTTP client or a package-provided sandbox mode. If the package exposes no fake, bind a test double for the service and keep one sandbox integration test that exercises real signing.

Gotchas and Tips

• Minimal release notes: 0.1.0 only links to the changelog. Pin the version in composer.json and review the diff before upgrading; there is no prior assessment to rely on for compatibility.
• Package type mismatch: the name says “bundle”, which is Symfony terminology. Verify Laravel auto-discovery and service-provider support before assuming it works as a native Laravel package.
• Callback verification: never trust a WeChat Pay Score notification without verifying the signature and decrypting the resource using the API v3 key. Reject unsigned or stale payloads.
• Certificate rotation: WeChat Pay platform certificates expire. Make the certificate path configurable and plan a rotation procedure; do not hard-code certificate contents.
• Amounts: WeChat Pay amounts are in cents. Keep your domain in integer minor units and convert only at the package boundary.
• Idempotency: use unique out_order_no values and handle duplicate callbacks. The package may retry or expose retry behavior; make your listeners idempotent regardless.
• Config caching: after changing .env credentials, run php artisan config:cache in deployments. Stale config is a common cause of signature failures.
• Logging: mask private keys, API v3 keys, and full request bodies in production logs. Log request IDs, order numbers, and response codes instead.
• Extension points: check whether the package allows a custom HTTP client, event dispatcher, or response handler. If not, keep your wrapper thin so you can replace the package without rewriting domain logic.
• Debugging order: verify merchant ID, serial number, private key format, API v3 key length, server time, and request signature in that order. Most integration failures are credential or clock issues, not business-logic errors.