Gateway Architecture
Commerce uses a driver-based gateway system. Every payment gateway is a PHP class implementing the PaymentGatewayModule interface. The GatewayRegistry singleton holds all registered gateways and resolves which ones are active (enabled and fully configured) at runtime.
This design means:
- All gateways are equal — built-in and third-party gateways use the same interface
- No view files are required per gateway — settings fields are declared in code and auto-generated in the admin UI
- Adding a new gateway is one file + one service provider registration
Built-In Gateways
| Gateway | Flow type | Card never hits server? | Refunds |
|---|---|---|---|
| Stripe | Inline | Yes (Elements tokenisation) | Automatic |
| PayPal | Inline | Yes (PayPal JS SDK) | Automatic |
| Authorize.net | Inline | Yes (Accept.js tokenisation) | Automatic |
| Mollie | Redirect | N/A | Automatic |
| 2Checkout | Redirect | N/A | Automatic |
| Bank Transfer | Manual | N/A | Credit note only |
Enabling Gateways
Go to Admin → Settings → Payment Gateways. Each gateway has:
- An Enable toggle
- Credential fields specific to the gateway
- A Webhook URL shown for reference (copy this when setting up webhooks in the gateway dashboard)
A gateway appears on the client payment page only when it is enabled AND configured (all required credential fields filled in).
[!IMPORTANT] Enabling a gateway with missing credentials will not show it to clients —
isConfigured()returns false and the gateway is excluded. There is no error shown; the gateway simply does not appear.
Flow Types
Inline Gateways
Stripe, PayPal, and Authorize.net render their payment form directly on the invoice payment page. The client never leaves the Commerce portal. Sensitive card data is tokenised in the browser by the gateway's JavaScript library — raw card numbers never reach your server.
Redirect Gateways
Mollie and 2Checkout redirect the client to an external hosted payment page. After payment (success or failure), the client is redirected back to Commerce. The invoice is marked paid via a webhook — not via the return URL, so the marking happens even if the client closes the tab.
Manual Gateways
Bank Transfer shows static bank details and records a pending payment. An admin must confirm the transfer manually. No automation, no webhook.
Webhook URLs
Each gateway that supports webhooks receives payment confirmation via a POST request to:
POST /webhooks/{slug}
These routes are CSRF-exempt and registered automatically. The slug matches the gateway's slug() return value:
| Gateway | Webhook URL |
|---|---|
| Stripe | /webhooks/stripe |
| PayPal | /webhooks/paypal |
| Mollie | /webhooks/mollie |
| 2Checkout | /webhooks/twocheckout |
| Authorize.net | Not required (JSON API response) |
Register these URLs in each gateway's dashboard — see the individual gateway setup guides for exact instructions.
Multiple Active Gateways
You can enable multiple gateways simultaneously. The client sees all active gateways on the payment page as selectable options. The order gateways appear on the payment page matches the order they are listed in Admin → Settings → Payment Gateways (drag to reorder).
[!TIP] A common configuration for European hosting companies: enable Stripe (cards), Mollie (iDEAL + SEPA), and Bank Transfer. This covers card payers, Dutch bank transfers, and corporate clients who prefer invoices.
Gateway Settings Auto-Generation
Each gateway declares its settings fields in the settingsFields() method. Commerce reads this and automatically generates the settings form in the admin UI. No Blade view files are required per gateway. Settings are stored as gateway_{slug}_{key} in the settings table and retrieved via:
GatewayRegistry::config('stripe', 'secret_key')
Third-Party Gateways
To add a gateway not built into Commerce, implement PaymentGatewayModule in a new class and register it in your service provider or config/commerce.php. The gateway will appear in Admin → Settings → Payment Gateways automatically. See Building a Gateway Module.