Pay Laravel Package

Product Decisions This Supports

• Multi-Payment Gateway Integration: Accelerates roadmap for supporting Alipay, WeChat, Douyin, UnionPay, Jiangsu Bank — and now Apple (Apple Pay on the web + App Store Server API for in-app purchases and subscriptions) — without building custom SDKs from scratch. Reduces technical debt by leveraging a PSR-compliant, battle-tested package with broad API coverage per provider.
• New channel unlocked: iOS monetization. Pay::apple() covers the full server-side surface for an iOS/web Apple strategy:
  • payToken — local verification/decryption of Apple Pay tokens (PKCS#7 cert chain + ECDH + AES-256-GCM) with zero new dependencies, so payment data can be validated in our own infrastructure.
  • merchantSession — Apple Pay web merchant validation proxy (mutual TLS passthrough), removing a custom backend service we would otherwise have had to build.
  • query — transactions, history, and subscription status (SubscriptionStatus enum / 1–5 whitelist).
  • callback — App Store Server Notifications V2 with JWS x5c verification and embedded-transaction JWS decoding, plus bundleId/environment ownership checks and certificate expiry validation.
• Product constraint to design around (Apple): there is no server-initiated refund and no cancel/close parity — those calls raise exceptions. Refunds are queried only, and subscription cancellation is an App Store Connect / client-side flow. Roadmap implication: customer-support tooling and refund policy must be defined outside the app, and any "one-click refund" or "cancel subscription" UX in our admin panel needs a manual/Store-side runbook. Also, digital goods on iOS must use App Store IAP (Apple's commission applies), so pricing/promo decisions differ from Alipay/WeChat.
• Build vs. Buy: Buy — avoids reinventing payment flows, callback validation, certificate management, and now Apple JWS/token cryptography. Justifies investment with 5.3K stars, MIT license, active maintenance, and a shipped Apple provider (feature #597) rather than an in-house spike.
• Use Cases:
  • E-commerce platforms (multi-tenant support for SaaS models).
  • Marketplaces (UnionPay + Alipay/Douyin for cross-border; Apple for cross-device checkout).
  • SaaS subscriptions (WeChat H5/App for Chinese users; Apple subscriptions for iOS users, queryable via _action: subscriptions).
  • Mobile-app-first products (new — previously out of scope for this package).
  • B2B/B2C hybrid (Jiangsu Bank eRong for regional dominance + WeChat for national reach).
• Tech Stack Alignment: Integrates with Laravel/Hyperf/Yii (official extensions). Swoole supported for high-concurrency. Note the Apple provider's RSA_v1 token decryption requires PHP ≥ 8.5 (OAEP-SHA256); the common EC_v1 path has no version constraint, so PHP 8.0+ is still viable for typical iOS volumes.
• Upgrade/roadmap cost (breaking change in this release): the config mode API is now enum-typed. ProviderConfigInterface::getMode() returns a PayMode enum instead of int, and Pay::MODE_NORMAL / MODE_SANDBOX / MODE_SERVICE constants are removed (use PayMode::*). Any code doing $config->getMode() === 1 silently evaluates false — a genuine correctness/incident risk for environment routing (e.g., accidentally pointing "sandbox" traffic at production credentials). Must be scheduled as a migration, not a drop-in bump. Mitigating: config still accepts legacy ints, and enum-ification is otherwise wire-compatible (payloads byte-identical); toJson()/json_encode() still emit 0/1/2.
• Compliance & Risk Mitigation:
  • Automated certificate rotation (WeChat public certs auto-fetched); Apple root/CA certificates bundled with override support, defaulting to safe behavior when unconfigured.
  • Local signature verification (no outbound API call to validate callbacks) — reduces latency and dependency on provider availability, and keeps sensitive payment data in-house.
  • PSR-14 event system for auditing payment flows (fraud detection hooks).
  • Multi-tenancy for shared infrastructure (fintech platforms with per-client gateways).
  • Typed error codes for Apple (PARAMS_APPLE_URL_MISSING, PARAMS_APPLE_TOKEN_INVALID, CONFIG_APPLE_INVALID, DECRYPT_APPLE_FAILED) — supports clean ops alerting and support-script routing.

When to Consider This Package

Adopt When:

• Targeting Chinese markets: Supports Alipay (60%+ market share), WeChat Pay (mobile-first), and UnionPay (mandatory for offline/online hybrid).
• Targeting iOS or Apple Pay on web (new): you need server-side Apple Pay token decryption, merchant session validation, App Store Server API queries, and App Store Server Notifications V2 handling — all four are now first-class, with bundled Apple CAs and ownership/environment checks aligned to Apple's reference libraries.
• Need rapid prototyping: Plugin architecture lets you enable/disable gateways without refactoring. Example: add Douyin support in <1 hour via Pay::douyin()->mini(); add Apple as a second provider behind the same Pay:: facade.
• High-security requirements:
  • Local signature verification (no API calls to validate callbacks).
  • Certificate management abstracted (WeChat auto-refresh; Apple bundled roots + expiry checks).
• Multi-tenant or SaaS: Built-in tenant isolation for shared payment infrastructure.
• Laravel/Hyperf stack: Official Laravel extension; minimal boilerplate.
• You can absorb a scheduled migration: teams with code comparing getMode() to ints or referencing Pay::MODE_* must budget a small, well-scoped refactor (and a test sweep for environment-routing assertions).

Look Elsewhere / Defer If:

• This specific release must go to production untouched: v3.8.0-beta.8 is a beta (published 2026-10-13). The removed constants and enum return type are breaking. Either stay on the current stable line for now, or pin the beta explicitly, validate in staging, and treat the mode refactor as a tracked work item with its own QA pass. Do not let a "patch bump" framing hide the API change.
• Non-Chinese, non-Apple focus: Coverage is Alipay/WeChat/UnionPay/Douyin/Jiangsu Bank/Apple. For global card acquiring (Stripe/PayPal/Adyen), use laravel-cashier or omnipay.
• You need server-side subscription control on Apple: no cancel/close, no server-initiated refunds — cancel/close throw. If the product requires lifecycle control from our backend, plan Store-side operational runbooks or complement with App Store Connect workflows.
• PHP < 8.0: Requires PHP 8.0+; legacy v2.x is deprecated. PHP < 8.5 is fine unless you specifically need Apple RSA_v1 token decryption.
• Custom gateway needs: If targeting non-supported providers (e.g., local banks), the plugin system is extensible but may require custom development.
• Real-time analytics: No built-in payment analytics dashboards (complement with Laravel Nova or ClickHouse).
• Offline/POS focus: Primarily API-driven (not POS SDKs), despite UnionPay card support.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us launch in China — and now on iOS — significantly faster by eliminating custom payment SDK development. With 5.3K stars, MIT licensing, and an Apple provider that just shipped, it remains the de facto standard for Alipay/WeChat/UnionPay in PHP."

• New opportunity: Apple Pay and App Store subscriptions are now in scope without a separate vendor or bespoke cryptography work — web Apple Pay merchant validation, token decryption, transaction/subscription queries, and App Store notifications are all handled.
• ROI: 3–6 months saved vs. building from scratch; the Apple workstream alone (cert chains, JWS verification, merchant session proxy) is typically 4–8 weeks of specialist engineering we no longer fund.
• Scalability: Swoole support for high-volume transactions (critical for marketplaces).
• Compliance posture improved: local signature/JWS verification, bundled and overridable Apple CAs, callback ownership + environment checks, certificate expiry validation, and typed error codes for clean audit trails.
• Cost & risk to be explicit about (don't oversell):
  • It's a beta. Shipping it requires a pinned version, a staging validation window, and a small migration for the mode enum breaking change (Pay::MODE_* removed; getMode() now returns a PayMode enum). Budget ~1 sprint across integration + QA, not zero.
  • Apple commercial rules apply: digital goods go through App Store IAP with Apple's commission, and Apple does not allow server-initiated refunds or cancellations — support and finance need a Store-side runbook.
  • Sequencing: recommend a Q3 China expansion decision now and treat Apple as a fast-follow once the v3.8 stable line lands, unless an iOS launch is already committed.

Ask: 'Should we prioritize this for our Q3 China expansion, with Apple as a fast-follow on the v3.8 stable release?'

For Engineering:

"This remains the most maintainable way to handle payments in PHP — and the Apple provider removes our two scariest build items: token cryptography and App Store notification verification. But this release has a real breaking change; here's the plan."

• Unified API: Pay::alipay()->web(), Pay::wechat()->mini(), Pay::apple()->payToken() — consistent patterns across gateways, one facade, one config model.
• Zero XML/JSON hell: abstracts Alipay's XML, WeChat's JSAPI, UnionPay's form submissions, and now Apple JWS (x5c) chains + nested transaction JWS.
• Apple internals are cleanly factored: AppleTrait is a thin facade (URL/ES256 JWT/crypto entry points); implementation lives in src/Crypto/Apple/ (Cryptor, TokenVerifier, JwsVerifier). Public API is unchanged by that refactor, and it's unit-testable in isolation — good for our coverage goals.
• Enums everywhere (low-risk, high-readability): PayMode, WeChat AppType / PapayScene / ReceiverType / VirtualPayEnv, Alipay ProductCode / BizCode, Apple SubscriptionStatus. Payloads are byte-identical and legacy ints/unknown values are still tolerated (unknown _type → MP, unknown env → production, unknown split type passthrough), so this is a typing improvement, not a protocol change.
• Performance: Swoole support + Guzzle under the hood for async requests.
• Debugging: PSR-3 logging and PSR-14 events for observability (e.g., hook into PayEvent::PAYMENT_SUCCESS).
• Certificates: WeChat public certs auto-refresh; Apple root/intermediate CAs ship in src/Certificate/ with apple_root_ca / apple_intermediate_ca overrides and validity checks.

Breaking changes to action before upgrade:

1. Pay::MODE_NORMAL / MODE_SANDBOX / MODE_SERVICE are removed → use Yansongda\Pay\Enum\PayMode; and reference PayMode::*.
2. getMode() now returns PayMode, not int — $config->getMode() === 1 is always false. Replace with ->isSandbox() / isService() / isNormal(). Grep for all mode comparisons in plugins and app code; this is the highest-severity item because a silent false can misroute environments. Add a test asserting sandbox vs. production routing.
3. AbstractConfig::getModeEnum() removed — fold call sites into getMode().
4. Legacy int config values ('mode' => 1) still work; toJson()/json_encode() still emit 0/1/2 — no storage or wire migration needed.
5. PHP version check: RSA_v1 Apple token decryption needs PHP ≥ 8.5 (OAEP-SHA256 parameter limits); EC_v1 is unconstrained. Confirm which token format our Apple flow sees before promising support on our current runtime.
6. Beta caveat: pin v3.8.0-beta.8 explicitly, validate in staging against real Alipay/WeChat sandboxes and an Apple sandbox environment, and land the mode refactor as its own PR.

Trade-offs:

• Learning curve: Laravel service containers + PSR standards → ~1-day ramp-up; add ~half a day for the Apple/ES256 JWT config surface (issuer_id, bundle_id, api_key_id, api_private_key).
• Vendor lock-in: Low — providers are modular and swappable.

Proposal:

1. Phase 0: Merge the mode-enum migration behind a test sweep (1 sprint slice); stay on stable line if Apple isn't needed yet.
2. Phase 1: Integrate Alipay + WeChat for MVP (2 sprints).
3. Phase 2: Add UnionPay for offline/online hybrid (1 sprint).
4. Phase 3: Add Apple (web Apple Pay + IAP/subscriptions), gated on v3.8 stable and an App Store Connect test account (1–2 sprints).
5. Phase 4: Extend multi-tenancy for SaaS clients.

Blockers to address:

• Secure storage for private keys — including the Apple ES256 API private key (Laravel vault or AWS KMS).
• Environment-routing tests after the PayMode migration (highest-risk regression).
• Rate limiting for callback retries (Guzzle middleware); App Store notifications can retry aggressively.
• Fallback logic if a gateway fails (e.g., redirect to Alipay if WeChat times out).
• Ops runbook for Apple: no server-side refund/cancel — define who acts in App Store Connect and how support is scripted.