Payfast Laravel Package

Technical Evaluation

Architecture fit

• omnipay/payfast is a driver for the Omnipay gateway abstraction layer, not a Laravel package. Fit is therefore conditional: it slots in cleanly if we adopt league/omnipay (or omnipay/common v3) as the payment port, and it maps naturally onto a ports-and-adapters design — define our own PaymentGateway contract, implement PayFastGateway that delegates to Omnipay\Omnipay::create('PayFast'), and keep Omnipay\* types out of domain code, controllers and Eloquent models.
• The driver models the correct PayFast flow: hosted redirect to a PayFast payment page, browser return to a returnUrl/cancelUrl, and out-of-band ITN (Instant Transaction Notification) webhook for authoritative settlement. This is an offsite/redirect integration, so PCI scope stays at SAQ-A and no card data touches our servers — a genuine architectural win versus an on-site form build.
• It is a poor fit for anything resembling auth/capture, partial capture, voids, or programmatic refunds. PayFast is effectively sale-at-time-of-payment with refunds performed in the PayFast dashboard; the driver will not give us a refund API we can build a back-office on. Any product requirement for automated refunds, partial refunds or multi-merchant splits should be treated as out of scope for this package.
• Currency is ZAR-only in practice. If the product is "South Africa expansion behind a region flag," fit is good. If it is "multi-currency global checkout," this is one adapter among many and must not shape the abstraction.

Integration feasibility

• Composer-level integration is trivial: add omnipay/payfast + omnipay/common (v3) and resolve a gateway from config. The real work is not the driver — it is the surrounding state machine: order → payment attempt → redirect → ITN receipt → signature validation → server-to-server confirmation → amount/merchant reconciliation → idempotent ledger write → order state transition. Budget for that, not for the install.
• Laravel wiring: credentials in config/services.php from env, a singleton gateway factory, two named routes (browser return + ITN webhook), the ITN route excluded from CSRF (it is application/x-www-form-urlencoded, not JSON), and the whole webhook handler pushed onto a queue after the synchronous validation step.
• Testing is workable: Omnipay ships a mock/test gateway and (in v3) an HTTPlug mock client, so happy-path and failure-path tests are cheap. What is not cheap is a faithful simulation of PayFast's ITN behaviour — we should build a signed-ITN fixture generator early.
• The 2022-04-16 release date and 24 stars mean we cannot assume parity with current PayFast documentation without verification. Treat the README as a starting hypothesis, not a specification.

Technical risk

• Provenance gap: repository is listed as unknown in the package metadata. Before anything else, confirm the actual source is thephpleague/omnipay-payfast (the canonical Omnipay driver home), verify the Packagist record, and diff the tagged release against the repo HEAD. An unverifiable repo is a supply-chain question, not a cosmetic one.
• Maintenance risk (high): last release 2022-04, ~24 stars, small contributor base. Likely dormant or single-maintainer. Assume we will own this code, not consume it.
• Signature scheme: PayFast signs the parameter string with an MD5 hash keyed by the merchant passphrase. This is legacy and weak by modern standards but is what the gateway mandates. Non-negotiables on our side: passphrase always set and stored as a secret, comparison via hash_equals, canonical parameter ordering and URL-encoding reproduced exactly (encoding/ordering/casing mismatches are the single most common breakage), and never trusting browser-returned parameters as evidence of payment.
• ITN validation completeness: confirm the driver performs all three checks — signature, server-to-server postback to PayFast's validate endpoint, and amount/merchant-ID match — or only the first. Signature-only validation is a fraud vector and would require us to layer the postback ourselves.
• Sandbox/live divergence: separate endpoints and separate credential sets, plus a distinct passphrase. A misconfigured environment is a realistic production incident; enforce environment binding in config with fail-fast on mismatch.
• No automated refunds/voids from the driver, and no capture separation. Any reconciliation or customer-service workflow must be built around the PayFast dashboard.
• PHP/Laravel drift: verify PHP 8.2/8.3 compatibility, omnipay/common ^3 pinning, Guzzle 7 / php-http/discovery conflicts, and deprecation noise. The driver uses HTTPlug, so we will run a second HTTP stack alongside Laravel's Http client — two clients to instrument, retry and observe.
• Currency and amount formatting: ZAR with two-decimal string formatting; add an explicit currency guard so a mis-set cart total in another currency cannot be submitted as ZAR.
• No first-party Laravel wrapper. barryvdh/laravel-omnipay and similar bridges are themselves stale; plan to resolve the gateway through Omnipay's factory in our own service provider rather than adding another abandoned dependency.

Key questions

1. Is the canonical repository and Packagist ownership confirmed, and does the 2022 tag correspond to current PayFast documentation?
2. Does the driver implement full ITN validation (signature + postback + amount/merchant match), and does it expose acceptNotification() or only completePurchase()?
3. Does it support tokenisation / recurring billing (token parameter, subscriptions), and if so, is card-token storage handled or only referenced?
4. Does it support refunds, voids, or any post-sale operation against PayFast's API, or is it purchase-only?
5. Are sandbox and live endpoints, credentials and passphrase cleanly separated and fail-fast validated?
6. What is the exact PHP and omnipay/common version matrix, and does it install cleanly on our Laravel 10/11 + PHP 8.2/8.3 baseline without conflicts?
7. Is there an on-site/non-redirect PayFast API path we would need for a smoother UX, and would that invalidate the driver's value?
8. Who owns this code internally after go-live, and are we prepared to fork it?
9. What is the merchant's PayFast onboarding status (account, passphrase, ITN URL whitelisting, sandbox credentials), and does it gate our timeline?
10. How does the business want refunds and reconciliation handled operationally if there is no API?

Integration Approach

Stack fit

• Laravel 10/11, PHP 8.2+, Composer, Redis + queue workers (Horizon) for ITN processing. The driver is framework-agnostic, so the Laravel surface area is: one service provider binding, one config block, one checkout controller, one webhook controller, one queued job, one reconciliation command.
• Adopt an internal PaymentGateway interface with PayFastGateway as the only class that imports Omnipay\*. This is the single most valuable design decision here — it means swapping to PayFast's native on-site API, or adding Ozow/Peach/Yoco for the ZA market, costs one adapter, not a checkout rewrite.
• Bind the gateway through a factory keyed by region/merchant, so ZA traffic can be toggled independently of the rest of checkout.
• Observability: emit structured events at redirect-issued, ITN-received, ITN-validated, ITN-rejected, order-settled. Because the driver uses HTTPlug rather than Laravel's HTTP client, wire the postback call into our logging/tracing explicitly.

Migration path

• Most likely starting point is either no ZA payment capability, or a hand-rolled PayFast form post scattered across a controller with inline MD5 signing. The package lets us retire that signing code and its tests into a maintained-ish driver, which is a net reduction in bespoke crypto.
• Use a strangler pattern rather than a big-bang cutover: stand up the adapter behind a feature flag scoped to internal testers and then a small merchant cohort; keep the legacy path live; run both against the same order state machine and compare outcomes in a reconciliation report before flipping defaults.
• If migrating from another ZA provider, run a parallel period where ZA orders can settle through either gateway by order ID range, with a single ledger writer so downstream finance sees one shape.
• Do not migrate historical transactions. Start the new path at a clean cutover date and leave prior data read-only.

Compatibility

• Pin exact versions in composer.json (omnipay/payfast, omnipay/common, HTTP client) and commit the lockfile. Do not allow float on a dormant package.
• Validate the full dependency graph against our PHP version and Laravel release in CI, including php-http/discovery behaviour when multiple HTTP clients are installed (a classic source of "works locally, fails in prod" ambiguity).
• Confirm the package's declared PHP constraint actually admits our runtime, not merely that it installs with --ignore-platform-reqs. Ignoring platform requirements on a payments dependency is not acceptable.
• Verify against both PayFast sandbox and live with a low-value real transaction before sign-off; sandbox-only validation has repeatedly proven insufficient for signature/encoding issues.

Sequencing

1. Week 1 — provenance and spike (3–4 days): confirm repo/Packagist ownership, read the source, run a sandbox purchase end-to-end, produce a written gap list against the Key Questions above.
2. Week 1–2 — contract and adapter: define the PaymentGateway port, implement PayFastGateway, wire config + service provider, feature flag off.
3. Week 2 — webhook hardening: ITN route, CSRF exemption, signature + postback + amount validation, idempotency key on PayFast's pf_payment_id, queued processing, dead-letter handling, replay-safe state transitions.
4. Week 2–3 — reconciliation and ops: nightly reconciliation command comparing gateway settlement report to our ledger, alerting on orphans and amount mismatches, back-office runbook for manual refunds.
5. Week 3 — QA and live proof: signed-ITN fixture suite, failure-path tests (missing ITN, duplicate ITN, tampered amount, wrong passphrase), one live low-value transaction, one live refund performed manually and reconciled.
6. Week 4 — staged rollout: internal → pilot merchant → full ZA traffic, with a documented rollback to the legacy path for the first two weeks.

Operational Impact

Maintenance

• Assume we own this package. Plan to vendor it (or maintain an internal fork published to a private registry) within the first quarter, and set a standing budget of roughly 2–4 engineer-days per year for security patches, PHP upgrades and PayFast documentation drift. That is cheap; the alternative — discovering at PHP 9 that the only maintainer stopped in 2022 — is not.
• Add the package to the SBOM and to the dependency-review gate so an unannounced release cannot reach production unreviewed.
• Contract tests are the maintenance lever: a fixture suite that asserts our generated signature and our ITN validation against known-good PayFast vectors will catch upstream and downstream drift faster than reading changelogs.
• Re-review PayFast's documentation and the fork annually, or immediately if PayFast announces API or signature changes.

Support

• No commercial support and no SLA. PayFast support covers the gateway, not the driver; the driver's issue tracker is best-effort and probably slow. Internal ownership is mandatory — name a primary and a secondary owner before go-live.
• Build a runbook covering: how to re-drive a stuck ITN, how to verify a disputed payment against PayFast, how to perform and record a manual refund, how to rotate the passphrase, and how to switch between sandbox and live without a deploy.
• Finance/CS need a non-engineering view: a payments dashboard or scheduled report showing pending, settled, rejected and reconciled counts. Without it, every anomaly becomes an engineer interrupt.

Scaling

• Scaling characteristics are favourable: PayFast hosts the payment page, so our load is bounded by checkout redirects plus ITN volume — one inbound webhook per transaction, plus one outbound validation postback per ITN. Throughput is governed by queue workers, not by the driver.
• The outbound postback is the bottleneck to watch: it is synchronous with PayFast's validate endpoint inside the validation step. Keep it short-timeout, retryable, and processed off the request thread where possible; make sure the ITN endpoint returns 200 quickly and enqueues rather than doing full reconciliation inline.
• Idempotency is the scaling invariant. Unique index on PayFast's pf_payment_id plus a transaction-state transition guard means duplicate ITN deliveries (which will happen) are harmless. Without it, retries turn into double-fulfilment.
• Data growth is small and linear; no special storage design needed.

Failure modes

• ITN never arrives (buyer closes browser, network loss, PayFast retry exhaustion) — money may be captured with no local record. Mitigation: scheduled reconciliation against PayFast's settlement/transaction report, plus a "pending > N minutes" alert.
• Duplicate or out-of-order ITN — mitigated by idempotency key and monotonic state transitions; must be explicitly tested.
• Signature mismatch — the dominant real-world failure: passphrase unset or wrong, parameter ordering, URL-encoding differences (spaces, +), case sensitivity in hash comparison. Presents as "every payment rejected"; a canary transaction on deploy is the cheapest detector.
• Amount or merchant-ID mismatch — a tampered or misconfigured ITN; must be a hard reject with an alert, never a soft pass.
• Environment crossover — a live deploy pointed at sandbox (or vice versa). Fail-fast config validation at boot, and separate secret scopes per environment.
• Currency error — a non-ZAR total submitted; guard at the adapter boundary.
• Refund expectation gap — a customer-service workflow assumes an API that does not exist. Surface this to the business early; it is a process design problem, not a bug.
• Abandoned redirects — orders left pending indefinitely; requires an expiry policy so the order table does not accumulate zombies.
• Driver abandonment — no patch for a future PHP or Laravel release. Mitigated by the fork decision above.

Ramp-up

• A mid-level Laravel engineer can get a sandbox payment working in half a day; the README plus Omnipay's examples are enough for the happy path. The webhook hardening, idempotency and reconciliation work is where the real 1.5–2.5 weeks sits, and it needs someone who has reasoned about payment state machines before.
• Knowledge concentration risk is high because the package is thinly documented. Force the spike output to be a written internal spec — signature canonicalisation, ITN validation steps, error taxonomy, environment matrix — so the knowledge is not in one person's head.
• Budget half a day of finance/CS enablement for the manual refund and reconciliation runbook, and schedule a 30-day post-launch review to check reconciliation variance and ITN rejection rates.
• Overall verdict: technically viable and low-effort to integrate, cheap to run, but strategically thin — a small, likely-unmaintained adapter for a regionally important gateway. Approve it as a scoped ZA adapter behind an internal interface, with an explicit decision to own or fork the code, and explicitly scope out automated refunds and multi-currency. Do not approve it as a strategic payments platform dependency.