Laravel Satim Laravel Package

Product Decisions This Supports

• Market entry into Algeria (feature/roadmap): the package is the payment rail for CIB/EDAHABIA card acceptance via SATIM. It supports the decision to launch checkout, paid plans, or a marketplace in-country without a bespoke integration project.
• Build vs buy: the integration surface (endpoints, parameter shapes, error taxonomy, order statuses) is already modelled, documented, and tested. The default decision should be integrate, reserving in-house build only for gateway features this package does not expose.
• Revenue leakage from abandoned payment pages: satim:reconcile plus SatimOrderReconciled closes the classic gap where a customer pays but never returns to the return URL. This is an operations/reporting decision (what do we do with a confirmed-but-unrecorded order?) as much as a technical one — product needs a policy for auto-fulfilment vs manual review.
• Regulatory posture: the audit trail with a ten-year default retention (article 12, Algerian code de commerce) turns a legal obligation into a config flag. Product can commit to an audit story in customer/partner conversations without commissioning extra work.
• Checkout UX completeness: Satim::supportMessage() and the error-code enum with per-operation description() enable a rejected-payment page that meets SATIM's requirement to display the hotline text, in FR/EN/AR — a localisation decision, not a translation chore.
• Test strategy and release cadence: Satim::fake(), named responses, per-operation queues, and facade assertions let payment paths live in CI. This is a decision to treat payment flows as regression-tested rather than manually verified before each release.
• Order identity: Satim::orderNumber() with collision avoidance against the audit trail removes a class of support tickets and duplicate-charge investigations; product does not need to design its own reference scheme.
• Vendor lock-in posture: SatimTransport bound to SatimClient is a real seam. It supports a future decision to add a second acquirer or a routing layer without rewriting checkout.

When to Consider This Package

Adopt when:

• You are a Laravel/PHP application selling to Algerian customers and need CIB/EDAHABIA card acceptance through SATIM.
• You want the error taxonomy, order statuses, and hotline copy handled rather than reverse-engineered from the integration guide.
• Audit and record retention matter to you (regulated commerce, finance reconciliation, dispute handling).
• You need reconciliation of payments where the customer never returned — i.e. your volumes are high enough that silent lost orders are a measurable cost.
• You want payment flows covered by automated tests rather than a staging sandbox and a checklist.
• You need French, English, or Arabic customer-facing payment copy.

Look elsewhere or plan to wrap it when:

• Your stack is not Laravel — the value here is in framework-native config, commands, events, and Eloquent-backed audit.
• You need a multi-gateway abstraction across countries (Stripe/Adyen/local acquirers). The SatimTransport seam helps, but this package is SATIM-shaped, not a general payment orchestration layer.
• You require a hosted/embedded checkout UI or drop-in components; this is a server-side integration.
• You cannot schedule model:prune or a scheduler at all — retention and reconciliation are opt-in, and unscheduled means unbounded audit growth and no recovery of stranded orders.
• You are unwilling to own contract testing against the real gateway. Satim::fake() replaces the transport; it cannot detect gateway drift.

How to Pitch It (Stakeholders)

For executives: this package is the fastest credible route to taking card payments in Algeria on our Laravel platform. It ships the compliance work we would otherwise have to design — a ten-year audit trail aligned to the Algerian commercial code — and it recovers revenue we would quietly lose when customers pay but never come back to the confirmation page. It is testable, so payment changes stop being a manual pre-release ritual, and the gateway sits behind an interface, so adding a second acquirer later is a contained piece of work rather than a rewrite.

For engineering: v1.1.0 introduces a SatimTransport contract as the fake seam, a complete SatimErrorCode enum with per-operation descriptions, an artisan reconciliation command with configurable after/within/limit, retention driven by satim.audit.retention and model:prune, and a first-class fake with named responses and facade assertions. Two items need attention in review: SatimOperation now carries its endpoint and the transport takes an operation rather than a string — verify any custom transport implementations — and the hotline wording changed in all three languages, so publish satim-lang if we have overrides. Reconciliation and pruning are inert until scheduled; treat the scheduler entries as part of the rollout, and check that a ten-year default retention is compatible with our data-retention and PII policies before it is relied on.