Checkout

Checkout converts a cart into a paid order. Storefront uses a two-step flow:

1. /checkouts/before — submit the cart, service quote, gateway, tip, and pickup/delivery flag. Storefront returns a token (and a Stripe clientSecret if the gateway is Stripe).
2. /checkouts/capture — once payment is confirmed by the customer's frontend, finalize by sending back the same token. Storefront creates one or more Fleet-Ops orders.

This split exists so the frontend can confirm payment with the gateway SDK (which keeps card data out of Fleetbase) and Storefront only needs to verify the gateway-confirmed token at capture time.

Step 1 — /checkouts/before

POST /storefront/v1/checkouts/before
Authorization: Bearer store_your_store_key
Customer-Token: 1|VlKK7lZ...

{
  "cart": "cart_abc123",
  "gateway": "gateway_stripe_id",
  "serviceQuote": "service_quote_id",
  "customer": "customer_abc123",
  "pickup": false,
  "tip": 200,
  "deliveryTip": 100
}

Required:

• cart — the cart's public id
• gateway — the gateway public id selected by the customer
• serviceQuote — the Service Quote id (omit for pickup orders)
• customer — the customer's public id

Optional:

• pickup — true for in-store pickup, defaults to delivery
• tip — driver tip in minor currency units (e.g. 100 = $1.00 USD)
• deliveryTip — separate delivery tip when delivery_tips_enabled
• is_cod — true if the customer is paying cash on delivery

Returns:

{
  "token": "checkout_token_abc",
  "clientSecret": "pi_xxx_secret_yyy"
}

For Stripe, the frontend uses clientSecret with the Stripe SDK to confirm the PaymentIntent (cards, Apple Pay, Google Pay). For QPay, the response includes the QPay invoice payload. For Cash on Delivery, no client-side payment is required.

Step 2 — /checkouts/capture

POST /storefront/v1/checkouts/capture
Authorization: Bearer store_your_store_key
Customer-Token: 1|VlKK7lZ...

{
  "token": "checkout_token_abc",
  "transactionDetails": { ... },
  "notes": "Leave at the front gate."
}

Required:

• token — the token returned by before

Optional:

• transactionDetails — gateway-specific confirmation payload
• notes — order notes for the merchant

On success, Storefront finalizes the cart and creates a Fleet-Ops order (or one order per store, for multi-cart checkouts in a network). The response contains the created order(s).

QPay Callback

QPay payments are completed by redirecting the customer to the bank app. After the bank confirms payment, QPay calls a public callback that Storefront uses to capture:

POST /storefront/v1/checkouts/capture-qpay

You don't call this directly — QPay does — but it must be reachable from QPay's network.

Pickup Orders

If the customer selects in-store pickup:

• No service quote is required (the serviceQuote field can be omitted)
• The order's activity flow uses the pickup_ready status instead of dispatching a driver
• The customer-facing app polls or subscribes to receive the ready notification, then collects in-store

Pickup is available when the store/network has options.pickup_enabled toggled on.

Required Minimum Amount

A store or network can require a minimum cart subtotal. Toggle options.required_checkout_min and set options.required_checkout_min_amount. If the cart subtotal is below the threshold, before returns a validation error.

Error Cases

The /before step validates that:

• The cart exists and is not expired
• The selected gateway is configured for the store/network
• The customer is authenticated (when authentication is required by your flow)
• The cart subtotal meets the minimum order amount (if configured)

The /capture step validates that:

• The token is valid and not yet used
• The gateway has confirmed the payment (for Stripe, that the PaymentIntent succeeded)

Handle errors by surfacing the API message to the customer and letting them retry without losing cart state.