Omnipay Alipay Laravel Package

Technical Evaluation

Architecture fit The package is a driver for the League Omnipay payment abstraction rather than a Laravel package per se. It exposes one gateway class per Alipay product line (web/express redirect, WAP, native App, and Alipay Open Platform "AOP" style calls) behind a uniform GatewayInterface: purchase, completePurchase (async notify + return), refund, query, close. That is a good architectural fit if the product already standardizes on Omnipay, because Alipay becomes one swappable driver among several and controller code stays gateway-agnostic. If we are not already on Omnipay, we would be adopting a second abstraction layer to integrate a single gateway — in that case the official Alipay Open Platform SDK (or a PSP aggregator) is a lighter, better-supported path.

Integration feasibility Mechanically straightforward: pure PHP, Composer-installable, MIT-licensed, no native extensions, no daemon. The redirect + server-to-server notify model keeps card data out of our systems and keeps PCI scope minimal. The notify/return pattern maps cleanly onto Laravel routes, middleware, and queued jobs. The real feasibility question is not "can we install it" but "does it speak the API surface our merchant account is provisioned for" — legacy MAPI/Express (create_direct_pay_by_user, MD5/RSA1) is closed to new merchants, so we must confirm the AOP gateway class is usable with RSA2 and app-certificate mode, not just key mode. Secondary blockers to verify in a spike: Composer constraints against Laravel 10/11 (PHP 8.1+, Guzzle 7), and whether omnipay/common resolves to a PHP 8-compatible version alongside this package's pins.

Technical risk — HIGH

• Unmaintained since 2020-05-22. No security patches, no PHP 8.x hardening, no response to Alipay API changes. We inherit ownership on day one.
• Signature verification is the crown jewel. completePurchase decides whether money actually arrived. A defect here is a direct fraud/free-goods vector. This code must be read, not trusted.
• Dependents = 0 despite 559 stars. Effectively no downstream consumers generating fixes; the star count reflects historical interest, not current battle-testing.
• API drift. Alipay deprecates endpoints and rotates toward certificate mode; a 2020-era client is likely fine for basic page-pay but risky for refunds, partial refunds, and cross-border/Global flows.
• Documentation and error semantics are Chinese-language and terse. Debugging failures costs more than the code review suggests.

Key questions

1. Which Alipay product line and merchant entity — China domestic (AOP), cross-border/Alipay+, or Antom/Alipay Global? They are different APIs under one brand.
2. Does our merchant account support RSA2 + certificate mode, and does this driver implement it?
3. What PHP and Laravel versions must we support over the next 24 months, and does the dependency tree resolve there today?
4. Are we willing to fork-and-own the package (assigned maintainer, CI, sandbox integration tests)?
5. Do we need refunds, partial refunds, query/close, and settlement reconciliation — and are all of those implemented and testable?
6. Is there an aggregator (Adyen, Airwallex, Checkout.com, PingPong, Oceanpayment) already under contract that removes this dependency?
7. What are the data-residency/compliance obligations (PIPL/CSL) if a China entity or China-hosted endpoint is involved?
8. Who on the team reads Chinese-language API documentation?

Integration Approach

Stack fit Treat Omnipay as an internal port. Do not wire the package into controllers. Define a PaymentGateway interface in the domain layer, implement AlipayOmnipayGateway against Omnipay\Common\GatewayInterface, and bind it in a PaymentServiceProvider. Configuration (app_id, private key, Alipay public key/cert, notify_url, return_url, sandbox flag) belongs in config/services.php + environment secrets, never in code. This keeps the blast radius of abandoning the package to one adapter class.

Migration path

• Greenfield: run a two-day spike against the Alipay sandbox before committing. If the spike fails on RSA2/cert mode or PHP 8, stop and go to the official AOP SDK or an aggregator — the cost of switching later is much higher.
• Existing Omnipay estate: drop-in, but pin the version explicitly and vendor/fork immediately; do not rely on upstream for fixes.

Compatibility Expect two concrete conflicts and resolve them at fork time: (a) PHP 8.1/8.2 deprecation notices and missing return types; (b) Guzzle/php-http pins colliding with Laravel 9+ (Guzzle 7). Forking and widening the constraint is usually a one-line Composer change plus a CI matrix run. Add PHPStan/Larastan at a modest level and a PHPUnit job that exercises signing/verification with fixed fixtures — those are the pieces that break silently.

Sequencing

1. Spike (week 1): sandbox credentials, one successful purchase → notify → refund loop, on our target PHP version.
2. Decide (week 1): adopt-as-fork vs. official SDK vs. aggregator. Record the decision and the reversal cost.
3. Fork and harden (weeks 2–3): vendor the package, pin, widen constraints, add CI + signature tests, add structured logging around every outbound call and inbound notify.
4. Adapter layer (weeks 3–4): config, service provider, DTO mapping, idempotent notify controller (dedupe key = out_trade_no + trade_no, enqueue and ack fast), query-based reconciliation job as the safety net for lost notifies.
5. Operational tooling (week 5): refund runbook, settlement report ingestion, alerting on signature failures and notify gaps.
6. Canary (week 6): feature-flag to a small traffic slice, watch conversion and error rates, then ramp.

Operational Impact

Maintenance Assume full ownership. Budget roughly 1–2 engineer-days per month for the first two quarters (dependency bumps, Alipay changelog review, sandbox regression), tapering to reactive afterwards. The recurring obligations are: tracking Alipay Open Platform deprecations, rotating keys/certificates on schedule (a silent expiry breaks checkout and refunds simultaneously), and keeping the fork's CI green against new PHP/Laravel releases.

Support Upstream support is effectively zero — stale issues, no releases in five years. Alipay's own support is Chinese-language, business-hours in CST, and routed through a merchant account manager; there is no developer-tier ticket queue for a self-hosted integration. This argues for a named internal owner and a written runbook rather than "ask the vendor."

Scaling The collection path is stateless redirect + async notify, so it scales horizontally with the app tier at no marginal cost. The real constraints are: (a) notify handling must be fast and idempotent — ack in well under a second and push fulfillment to a queue, because Alipay retries on non-2xx with a widening schedule and will eventually give up; (b) egress latency/reliability to Alipay endpoints from US/EU regions is materially worse than from Asia — consider a regional egress or a cross-border endpoint; (c) refund throughput is bounded by Alipay-side rate limits, so batch and queue.

Failure modes to instrument

• Signature verification failure (key rotation, cert mismatch, charset/encoding) → hard-fail and alert; never fall through to "assume paid."
• Lost or delayed notify → order stuck in pending; mitigate with scheduled query reconciliation over in-flight orders older than N minutes.
• Duplicate notify → double fulfillment; mitigate with a unique constraint on (gateway, trade_no) and idempotent handlers.
• Refund async/timeout → silent customer-visible discrepancy; reconcile against the daily settlement file.
• Timestamp skew on signed requests → intermittent, hard-to-reproduce auth errors; enforce NTP and log the raw request/response.
• Cross-border FX and settlement currency mismatches → accounting drift; capture the settled amount and currency from Alipay, not from our own calculation.

Ramp-up Two to three weeks of effective ramp for an engineer unfamiliar with Omnipay and Alipay: the codebase is small, but the failure modes are learned only by running the sandbox loop repeatedly. The Chinese-language docs and the absence of a working upstream example set add roughly 30–40% to the spike duration. Front-load the spike specifically to de-risk the RSA2/cert path — that is where this package is most likely to cost the most time, and where a "no" answer most cheaply redirects the plan to an aggregator.