Docs / Payments & Mailpit

Payments, Mailpit, and Installer Updates

This release adds sandbox-only payment links, a local simulator gateway, refund testing, Mailpit mail testing, and a cleaner installer flow.

Payment Gateways

Payments are configured under Settings - Payments and are locked to sandbox mode. The module creates standalone payment requests with public links at /pay/{uuid}. Future restaurant orders or invoices can attach through the nullable polymorphic payable fields.

The Simulator gateway works on localhost with no external credentials.
Stripe uses Checkout Sessions with test keys.
PayPal uses Orders v2 against the sandbox API.
Razorpay uses Orders plus Checkout.js test keys.
Paystack uses transaction initialize and verify APIs.

Payment Sandbox Lab

Open Payments - Sandbox Lab after installation. The lab shows enabled gateways, webhook URLs, sandbox scenarios, health checks, recent transactions, and a sample request generator. The simulator supports success, failure, cancellation, delayed webhook confirmation, full refunds, and partial refunds.

Use /pay/{uuid} to open a public sandbox checkout link.
Use /payments/simulator/checkout/{uuid} for local simulator outcomes.
Use /payments/webhooks/{gateway} for provider webhooks.
Use transaction details to reconcile or refund paid sandbox transactions.

Mailpit

Select mailpit in the installer or Settings - Channels for local mail capture. The SMTP host is 127.0.0.1, the port is 1025, and encryption, username, and password are blank. Open the Mailpit web UI at http://127.0.0.1:8025. Payment request detail pages can email payment links through the configured mailer, so Mailpit is the recommended local verification path.

Installer Changes

Installer pages no longer render the shared full-page loader.
Installer background graphics and pseudo-graphics are disabled.
Step 6 now validates password_confirmation with Laravel's confirmed rule.
Step 5 saves Mailpit and sandbox payment settings before continuing.

Sandbox Testing

Live Stripe and Paystack keys are rejected. Razorpay key IDs must start with rzp_test_. PayPal is forced to https://api-m.sandbox.paypal.com.

Set PAYMENT_DEFAULT_GATEWAY=simulator for a credential-free demo.
Set PAYMENT_SANDBOX_PUBLIC_URL when provider webhooks need a public staging URL.
Keep real provider webhooks on test/sandbox mode only.
Use Mailpit to confirm sent payment links before testing gateway redirects.

php artisan migrate
php artisan db:seed --class=SettingSeeder
php artisan db:seed --class=RoleAndPermissionSeeder
php artisan test

Webhook Endpoints

All gateways post to /payments/webhooks/{gateway}. Webhook signatures are verified before local transaction status changes, and gateway event IDs are stored idempotently.

The transaction detail page stores a timeline for checkout starts, gateway responses, returns, webhooks, reconciliation, refunds, and failures. Duplicate webhook events are acknowledged but not processed twice.