Payment Gateways
Configure Stripe, QPay, and Cash payment gateways — credentials, capabilities, sandbox mode, webhooks, and the gateway transaction audit log.
Payment Gateways
Payment Gateways are the external services that process real money. Ledger ships with three drivers — Stripe, QPay, and Cash — and exposes a PaymentGatewayManager::extend() API for registering custom drivers from a service provider.
Navigate to Ledger → Payments → Gateways.
Supported Gateways
| Gateway | Driver | Use Case |
|---|---|---|
| Stripe | stripe | Card payments and digital wallets globally |
| QPay | qpay | Invoice-based payments for Mongolian banks |
| Cash | cash | Manual/offline payments and refunds |
Gateway Capabilities
Each driver advertises the operations it supports. Check capabilities before invoking an operation.
| Capability | Stripe | QPay | Cash |
|---|---|---|---|
purchase | ✓ | ✓ | ✓ |
refund | ✓ | ✓ | ✓ |
tokenization | ✓ | — | — |
setup_intent | ✓ | — | — |
checkout_session | ✓ | — | — |
webhooks | ✓ | ✓ | — |
sandbox | ✓ | ✓ | — |
recurring | ✓ | — | — |
Adding a Gateway
Navigate to Ledger → Payments → Gateways.
Click New Gateway.
Enter a Name and select the Driver (stripe, qpay, or cash).
Fill in the fields shown by the driver's config schema (see below).
Set Environment to sandbox while testing, live for production. The boolean is_sandbox is kept in sync automatically.
Click Save.
The form also exposes optional Return URL and Webhook URL fields. The system-generated webhook URL is displayed beneath the user-entered field for reference.
Stripe Configuration
| Field | Description |
|---|---|
| Publishable Key | pk_test_... or pk_live_... |
| Secret Key | sk_test_... or sk_live_... |
| Webhook Signing Secret | whsec_... — from Stripe Dashboard → Webhooks |
| Show Postal Code | Whether the card field requires a postal code |
| iDEAL Payment | Enable iDEAL (Netherlands) |
| FPX Payment | Enable FPX (Malaysia) |
Register the Ledger webhook URL (shown beneath the user-entered field on the gateway form) in the Stripe Dashboard so Stripe can notify Fleetbase of charge.succeeded, charge.failed, and charge.refunded events.
QPay Configuration
| Field | Description |
|---|---|
| Username | QPay merchant username |
| Password | QPay merchant password |
Invoice Code (invoice_code) | QPay invoice type code |
Cash Configuration
The Cash driver supports purchase and refund and is useful for recording manual / offline payments and refunds without an external processor.
| Field | Description |
|---|---|
| Label | Optional label shown to operators |
| Instructions | Optional payment instructions surfaced to customers |
Security
Gateway credentials are:
- Stored encrypted at rest using Laravel's
encrypted:arraycast against yourAPP_KEY - Never exposed in API responses
- Decrypted only in memory when a payment operation is executed
Gateway Transaction Audit Log
Every interaction with a gateway (charge, refund, webhook) is logged as a GatewayTransaction. The log is the idempotency key store — duplicate webhooks are deduplicated using GatewayTransaction::isProcessed(), a check on (gateway_reference_id, event_type).
View the log for any gateway:
- Open the gateway in Ledger
- Click the Transactions tab
The log includes status, amount, gateway reference ID, raw response, and processing timestamp — useful for debugging payment issues.
Extending with Custom Drivers
Register a custom driver from a service provider:
use Fleetbase\Ledger\PaymentGatewayManager;
PaymentGatewayManager::extend('mygateway', function () {
return new MyCustomDriver();
});Your driver class implements the standard payment gateway contract (charge, refund, getCapabilities, getConfigSchema, etc.) and will appear in the gateway picker once registered.