Payline Sdk Laravel Package

Technical Evaluation

Architecture fit. monext/payline-sdk is a vendor-authored, framework-agnostic PHP client for Monext Payline — a French PSP with strong domestic Cartes Bancaires coverage. It is not a Laravel package: no service provider, facade, config file, or migration. That is not a blocker, but it fixes the shape of the integration: the SDK must live behind an anti-corruption layer exposing an internal PaymentGateway contract (authorize, capture, refund, status). Payline's vocabulary — merchant contracts, wallets, DoWebPayment/DoAuthorization operations, Payment/Transaction/Order objects — should not leak into controllers, models, or domain events. Treat it as a transport adapter, not an application dependency.

Integration feasibility. Composer-installable and namespace-isolated, so it coexists with a standard Laravel skeleton. The real work is resolving four unknowns before estimation:

• PHP constraint — whether the declared range (^7.4|^8.0 or narrower) matches the Laravel version we target.
• Extension requirements — historically Payline SDKs lean on ext-curl, ext-json, and sometimes ext-soap; a missing SOAP extension is a container-build blocker.
• HTTP transport — if the SDK bundles its own client rather than using Guzzle, we lose Laravel's retry/middleware/timeout conventions and must configure both layers.
• Sandbox parity — the homologation environment diverges from production in test-card behavior, 3DS simulation, and contract scoping; not always documented.

Technical risk. Moderate, concentrated in four areas:

• Adoption signal is misleading. Zero stars and zero dependents look alarming, but GitHub dependents is a poor proxy for PHP adoption — Composer install counts are what matter and are not captured here, and vendor SDKs are often mirrored from internal repositories. The correct read is "adoption unknown," not "unproven." It does mean we will be an early integrator and should expect rough edges.
• Vendor lock-in via API surface. Payline's model is idiosyncratic, and stored card tokens do not migrate across PSPs. Switching later means re-tokenizing cards and rebuilding the adapter — a commercial and product consequence, not just an engineering one.
• PCI scope is a decision, not an implementation detail. Hosted payment page / embedded widget keeps us in SAQ A-EP; direct-API card capture pushes toward SAQ D-EP and expands audit, logging-redaction, and key-management obligations. Settle this before code is written.
• Error semantics. SDKs of this vintage tend to surface vendor error codes as generic exceptions or raw arrays. Mapping retryable vs. terminal, and distinguishing "declined" from "unknown," is our work and belongs in the adapter contract tests.

Key questions to answer before committing.

1. Which integration mode does the business need — hosted page, widget, or direct API? This drives PCI scope and timeline more than anything else.
2. Does the SDK expose a merchant-supplied reference/idempotency field for duplicate-charge protection?
3. Is there a webhook/IPN signature verification helper, or do we implement verification ourselves?
4. What is the release cadence, last-commit date, and endpoint deprecation policy?
5. Does it cover the payment methods we actually need (cards, SEPA, wallets, recurring) or only a subset?
6. What is the Monext commercial support SLA, and is it tied to our merchant contract rather than the repository?

Integration Approach

Stack fit. Target Laravel 10/11/12 on PHP 8.1+. Concrete shape:

• config/payline.php sourcing merchant ID, access key, contract number, and environment from env vars; secrets from Vault or AWS Secrets Manager, never .env in production images.
• app/Services/Payments/PaylineGateway.php implementing the internal PaymentGateway interface, with domain events (PaymentAuthorized, PaymentFailed, PaymentRefunded) emitted from the adapter so the rest of the app stays PSP-agnostic.
• A thin HTTP layer with explicit connect/read timeouts (5s/15s) and a circuit breaker in front of the adapter.
• A single owned reconciliation service keyed on merchant reference — the piece most likely to be under-scoped and most likely to matter during an incident.

Migration path. Five stages, each with a go/no-go gate:

1. Spike (1 week). Sandbox merchant account, standard test cards, documented actual request/response payloads. Output: internal API notes doc. Vendor docs and SDK behavior drift; do not skip this.
2. Adapter + contract tests. Build against the sandbox with a real test suite, not mocks. Include failure paths: timeout, decline, malformed response, 3DS abandonment.
3. Shadow mode. Run log-only alongside the current PSP for a sample of live checkouts; diff intended outcomes. Two to four weeks, or until divergence is understood.
4. Canary. Route 5% of traffic, or a single payment method, through Payline. Watch authorization rate and latency against baseline.
5. Cutover with a warm rollback. Keep the previous PSP provisioned for at least 30 days.

Compatibility and sequencing. Card-on-file tokens do not migrate across PSPs — budget for hosted re-entry or network token migration, whichever the network and business allow. Sequence delivery so each stage is independently shippable and revertible: (1) auth + configuration, (2) authorize/capture, (3) webhook receipt and verification, (4) refunds and partials, (5) recurring/subscriptions, (6) 3DS and fraud-screening rules. Commercially, sequence the merchant contract before the SDK — the SDK is only useful inside that relationship, and the decision to route French volume through Payline is a product decision this library merely enables.

Operational Impact

Maintenance. Low volume but non-zero. Pin an exact version in composer.json, subscribe to the release feed, and budget two to four hours per quarter for review and upgrade. The larger cost is not the library — it is Payline endpoint version deprecations and the reconciliation and reporting tooling we build around it.

Support. The repository is not the support channel. Escalation runs through the Monext account manager and merchant contract; GitHub issues are likely low-traffic and slow. Establish a named support contact and documented escalation path during onboarding, not during the first incident. Support is French-first — confirm English-language coverage for our operating hours.

Scaling. The SDK is stateless per request, so throughput is bounded by Payline's contract-level rate limits and per-transaction latency (typically 300–1500ms, higher with a 3DS redirect). Two implications: keep payment calls out of long synchronous request cycles, and do not assume horizontal scaling of our app solves throughput — the constraint is the vendor's API tier in our contract. Size the API tier against peak checkout, not average.

Failure modes to design for now.

• Unknown state after timeout. The transaction may have succeeded while our request failed. Mandatory: a reconciliation job that polls by merchant reference and resolves orphans. Without it, this becomes duplicate charges or silent revenue loss.
• Lost webhooks. Assume delivery is not guaranteed. Daily reconciliation against Payline's transaction report is the source of truth.
• Duplicate submissions. Enforce a client-generated idempotency key per payment attempt.
• 3DS abandonment. Model the redirect-return path explicitly, with resumable order state rather than fire-and-forget.
• Rounding and currency. Verify minor-unit handling for every currency in scope; French-market defaults can mask EUR-specific assumptions.
• Test coverage gaps. The SDK's tests will not cover our failure paths. Our contract tests are the safety net.

Ramp-up. A competent Laravel engineer becomes productive against the adapter in one to two days; full fluency — Payline's contract/wallet model, sandbox quirks, 3DS return handling, reconciliation — takes two to three weeks of real integration work. Add vendor onboarding lead time (merchant account, contract numbers, sandbox credentials) as a separate, often longer, calendar risk. For the TPM, the launch-readiness gates are: PCI scope confirmed and documented, reconciliation running in staging, rollback rehearsed, named Monext escalation contact on file, and baseline metrics (authorization rate, p95 latency, decline-code mix, orphan-transaction count) captured before canary.