Download the PHP package syriable/laravel-payments without Composer

# Laravel Payments A lightweight Laravel package for accepting payments through **Stripe**, **PayPal**, and an open ecosystem of community gateway plugins. It does one thing well: it unifies payment gateways behind a small, Laravel-native API. It is **not** an accounting system, a subscription engine, or a billing platform. It ships a single table to make webhook delivery durable, and otherwise stays out of your schema — it never models your domain for you. ## Why this package - **Tiny core.** A manager, a contract, three DTOs, two gateways. You can read the whole thing in an afternoon. - **Laravel-native.** Built on `Illuminate\Support\Manager` — the same pattern behind `Cache`, `Mail`, and `Storage`. Nothing new to learn. - **Financially safe by design.** Amounts are integer minor units. No floating-point math touches money, anywhere. - **No hard SDK dependencies.** Gateways use Laravel's HTTP client. Your `vendor/` directory stays lean. - **Plugin-friendly.** Add a gateway in ~20 lines, in your own Composer package, shipped on your own schedule. ## Requirements - PHP 8.3+ - Laravel 12 or 13 ## Installation The service provider and the `Gateway` facade are auto-discovered. Publish the config: Verified webhooks are persisted before processing (see [Webhooks](#webhooks)), so publish and run the migration: Prefer not to store webhooks? Set `webhook.store` to `Syriable\Payments\Store\NullWebhookStore::class` and skip the migration. Then set your credentials in `.env`: `STRIPE_WEBHOOK_SECRET` and `PAYPAL_WEBHOOK_ID` come from each provider's dashboard when you register your webhook endpoint (see [Webhooks](#webhooks)). Until they are set, incoming webhooks fail signature verification and return `403` — so configure them before going live. ## Usage ### Checkout `checkout()` returns a `PaymentResult`: > **Amounts are always integer minor units.** `2500` means `$25.00`, > `100` means `$1.00`. Never pass a float or a major-unit value like `25.00` — > `Checkout` rejects non-positive amounts at construction, but it cannot tell > `25` cents from `25` dollars. Keeping money as integers is what makes the > package financially safe; no floating-point math touches an amount anywhere. > **Store `$result->id` on your order.** This is the gateway's identifier for > the payment, and it is how the webhook later reconciles back to your order > (see [Webhooks](#webhooks)). A typical checkout persists it immediately: > > ### Reconciliation Webhooks can be lost (downtime, deploys, secret rotation). `retrieve()` pulls the authoritative state straight from the gateway, so you can reconcile orders stuck in a non-final state: `retrieve()` also returns `$reference`, `$amount`, and `$currency` when the gateway exposes them, so you can verify a reconciled payment exactly as you would a webhook. For the common case — re-emit the canonical event so your existing webhook listeners fire — use the `ReconcilePayment` job or the command: The package doesn't own your orders table, so iterate your own non-final orders on a schedule and reconcile each. Terminal states re-dispatch `PaymentSucceeded` / `PaymentFailed` / `PaymentRefunded`; non-terminal states emit nothing. ### Refunds Refunds are an opt-in capability. Check for it with `instanceof` — the type system tells you whether a gateway supports it: ### Webhooks The package registers one webhook route automatically: Register that URL in each provider's dashboard. The controller verifies the request's signature, then dispatches one of three events. You listen for them in your own application: Events: `PaymentSucceeded`, `PaymentFailed`, `PaymentRefunded`. Each carries a normalized `WebhookEvent` with `$gateway`, `$type`, `$paymentId`, `$reference`, `$amount`, `$currency`, `$eventId`, and the full verified `$payload`. The controller verifies the signature, persists the event, drops duplicates, and acknowledges immediately; the events are dispatched from a queued `ProcessWebhookEvent` job so a slow listener can't make the gateway time out and retry. Point it at a real queue with `webhook.connection` / `webhook.queue` (defaults to the application's queue). Verified webhooks are persisted to the `payment_webhook_calls` table before processing (status `pending` → `processed`/`failed`), giving you a durable, auditable record and a place to replay from. Persistence is swappable via the `webhook.store` config key — the default is `Store\DatabaseWebhookStore`; ship your own `Contracts\WebhookStore`, or use `Store\NullWebhookStore` to disable it. Invalid signatures return `403` and dispatch nothing. Unknown gateways return `404`. > **Make your listener idempotent.** Gateways legitimately deliver the same > webhook more than once. Guard against double-processing — e.g. skip the > handler if the order is already marked paid. > **Keep the webhook route off the `web` middleware group.** `web` enables > CSRF protection, which rejects server-to-server webhook requests. The > default config uses `api`; change `webhook.middleware` only to something > equally CSRF-free. ## Observability The package logs the money-movement boundaries — `payments.checkout.created`, `payments.refund.issued`, `payments.webhook.received`, `payments.webhook.duplicate`, and `payments.webhook.invalid_signature` — with ids, references, and amounts (never secrets or full payloads). Route them to their own channel: Leave it unset to use the application's default channel. ## Adding a custom gateway Two ways. For a one-off, register it in `AppServiceProvider::boot()`: For something reusable, ship it as its own Composer package. A gateway plugin is just a package whose service provider calls `Gateway::extend()`: Your gateway class implements the `Gateway` contract — and, optionally, `Refundable`: That's the entire plugin API. No plugin interface, no registry, no manifest. ## Testing Swap in a fake gateway with one call. No HTTP, no real charges: Available assertions: `assertCheckedOut()`, `assertRefunded()`, `assertNothingCharged()`, `assertCheckoutCount()`. ## Configuration The published `config/payment-gateways.php` is intentionally small: ## Architecture at a glance ## Running the package test suite Static analysis and code style: ## Changelog Please see [CHANGELOG.md](CHANGELOG.md) for details on what has changed recently. ## Security If you discover a security vulnerability, please email **[email protected]** rather than using the issue tracker. Webhook handlers verify signatures before parsing — Stripe via HMAC-SHA256, PayPal via its verification API. A failed verification returns `403` and dispatches no events. ## Credits - [Syriable](https://github.com/syriable) - [All Contributors](../../contributors) ## License The MIT License (MIT). See [LICENSE.md](LICENSE.md).