Payment Gateways
Configure payment gateways for Storefront — Stripe, Braintree, QPay, Manual, and Cash on Delivery.
Payment Gateways
To accept payments, configure one or more Payment Gateways in your store or network settings. Storefront supports four gateway schemas, plus a separate Cash on Delivery toggle.
Navigate to Storefront → Settings → Gateways to configure gateways.
Supported Gateways
| Gateway | Type | Notes |
|---|---|---|
| Stripe | Card / digital wallet | Global; supports test mode, Apple Pay, Google Pay |
| Braintree | Card / PayPal | Global PayPal/Braintree |
| QPay | Bank-app invoice | Mongolian banking ecosystem |
| Manual | Offline / wire | For invoicing, bank transfer, or any custom payment instructions |
Cash on Delivery is not in the gateway picker — it is enabled separately by toggling options.cod_enabled on the store or network.
Adding a Gateway
Navigate to Storefront → Settings → Gateways.
Click New Gateway.
Select the gateway type.
Enter the credentials and configuration (see per-gateway tables below).
Toggle Sandbox on while testing.
Click Save.
Every gateway has these common fields:
| Field | Description |
|---|---|
| Name | Display label shown to customers (e.g., "Card") |
| Code | Immutable identifier (set once, derived from the schema) |
| Callback URL | URL the gateway calls after payment (you fill this in based on the provider's docs) |
| Return URL | URL the customer is redirected to after payment |
| Sandbox | Toggle test mode |
Stripe
| Field | Description |
|---|---|
| Publishable Key | Stripe public key (starts with pk_test_ or pk_live_) |
| Secret Key | Stripe secret key (starts with sk_test_ or sk_live_) |
| Show Postal Code | Whether the card field requires a postal code |
| iDEAL Payment | Enable the iDEAL payment method (Netherlands) |
| FPX Payment | Enable the FPX payment method (Malaysia) |
Stripe Payment Flow
- Frontend calls
/checkouts/beforewith the Stripe gateway selected - Storefront creates a Stripe
PaymentIntentand returns theclientSecret - Frontend confirms the payment with the Stripe SDK (PaymentSheet or CardField)
- Frontend calls
/checkouts/capturewith the same token - Storefront verifies the PaymentIntent status with Stripe and finalizes the order
Raw card numbers never touch the Fleetbase API — PCI compliance is maintained.
Braintree
| Field | Description |
|---|---|
| Merchant ID | Braintree merchant ID |
| Public Key | Braintree API public key |
| Private Key | Braintree API private key |
| Tokenization Key | Client-side tokenization key (optional) |
QPay
| Field | Description |
|---|---|
| Username | QPay merchant username |
| Password | QPay merchant password |
| Invoice ID | QPay invoice type code |
| Ebarimt Invoice ID | Ebarimt receipt ID for tax reporting |
| District Code | Tax district code |
QPay payments are completed via bank-app deep links. After the customer pays in their bank's app, QPay POSTs to the public callback POST /storefront/v1/checkouts/capture-qpay, which Storefront uses to capture the order.
Manual
The Manual gateway is for offline payment methods (bank transfer, invoicing, in-person handoff). Configure it with whatever fields your workflow needs:
| Field | Description |
|---|---|
| Public Key, Private Key, Key ID, Key Secret | Generic credential slots — use as needed |
| Contact email shown to customers | |
| Name | Receiver name |
| Details | Free-form payment details |
| Payment Instructions | Instructions surfaced to the customer at checkout |
Cash on Delivery
To enable COD:
- Open the store or network's general settings
- Toggle Enable cash on delivery (
options.cod_enabled) to on - Save
When enabled, "Cash" appears as a payment option at checkout alongside any configured gateways. COD orders are created without payment capture — the driver collects cash and confirms receipt in the Navigator app. The order's transaction is recorded as pending and unpaid, and is settled for the amount collected when the order is completed. See Payment Status.
Refunds
Refunds for edited and canceled orders go back through the gateway that took the payment. Stripe refunds any amount; QPay refunds whole payments only; other gateways can't refund, so the money is given as store credit instead. See Payment Status.
Sandbox Mode
All gateways support a Sandbox toggle. Enable sandbox during development — no real charges are made. Switch to live credentials before going to production. Cash on Delivery has no sandbox concept — payment is collected in person.
Gateway per Store vs. per Network
Gateways can be configured at the store level or the network level:
- Store-level gateways are available only to that store's checkout
- Network-level gateways are shared by every store in the network
Customers browsing a network see the gateway options configured on the network. Gateways are not implicitly inherited from store to network or vice versa — configure them where they apply.