FleetbaseFleetbase

Checkout

Checkout endpoints turn a cart into a payable order flow. Use them to initialize gateway-specific payment data, check checkout status, capture payment callbacks, and create orders from completed checkouts.

The Checkout object

A checkout token represents a prepared storefront checkout session for a cart, customer, gateway, and delivery or pickup option.
Attributes
tokenstringoptional

Checkout token used to capture the order.

paymentIntentstringoptional

Stripe PaymentIntent ID when using Stripe checkout.

clientSecretstringoptional

Stripe client secret when using Stripe checkout.

ephemeralKeystringoptional

Stripe ephemeral key when returned for mobile checkout.

customerIdstringoptional

Gateway customer ID.

invoiceobjectoptional

QPay invoice payload when using QPay checkout.

checkoutstringoptional

Public checkout ID returned by QPay checkout initialization.

The Checkout object
{
  "token": "checkout-token",
  "paymentIntent": "pi_123",
  "clientSecret": "pi_123_secret_456",
  "ephemeralKey": "ek_test_123",
  "customerId": "cus_123"
}
GET/v1/checkouts/before

Before ❗

Initializes a checkout preview for a cart, customer, gateway, and delivery or pickup option. The response prepares gateway-specific client data or a checkout token before the order is captured.

Promotions are priced when the checkout is created: automatic promotions and any promo codes (from promo_codes or applied to the cart) are subtracted from the amount charged, and each use is reserved for the checkout. A code that cannot be applied refuses the checkout with 400.

Query parameters
gatewaystringoptional

Payment gateway ID or code.

customerstringoptional

Customer public ID for guest checkout. When Customer-Token is present this value must identify the authenticated customer or checkout returns 403.

cartstringoptional

Cart public ID or unique identifier. Network checkout validates member stores, online state, products, locations, currency consistency, and the network multi-cart policy before payment initialization.

service_quotestringoptional

Service quote ID used by the request.

cashbooleanoptional

Cash value for this checkout request.

pickupbooleanoptional

Pickup address, place ID, or pickup payload for the order.

tipnumberoptional

Tip amount applied to the checkout.

delivery_tipnumberoptional

Tip amount allocated to delivery.

promo_codesarray of stringsoptional

Promo codes to apply, as an array or a comma separated string. promo_code and discount_code are accepted for a single code. Codes already applied to the cart are always included. The checkout is refused with 400 and promotions.rejected[] (\{ code, reason \}) when a code cannot be applied; the discount of the storefront's automatic promotions is applied without a code.

GET/v1/checkouts/before
curl https://api.fleetbase.io/v1/checkouts/before?gateway=stripe&customer={{customer_id}}&cart={{cart_id}}&service_quote={{service_quote_id}}&pickup=false \
  -H "Authorization: Bearer flb_live_…"
GET/v1/checkouts/before

Before Cash Pickup Checkout

Initializes a cash (cash-on-delivery) pickup checkout. A pickup checkout with the cash gateway needs no delivery service quote, so the service_quote parameter is omitted. The response returns the checkout id and token; no gateway client data is prepared for cash.

Query parameters
gatewaystringoptional

Payment gateway code — cash for a cash-on-delivery checkout.

customerstringoptional

Customer ID associated with the request.

cartstringoptional

Cart value for this checkout request.

pickupbooleanoptional

Set true for a pickup order; a cash pickup checkout needs no service quote.

promo_codesarray of stringsoptional

Promo codes to apply, as an array or a comma separated string. promo_code and discount_code are accepted for a single code. Codes already applied to the cart are always included. The checkout is refused with 400 and promotions.rejected[] (\{ code, reason \}) when a code cannot be applied; the discount of the storefront's automatic promotions is applied without a code.

GET/v1/checkouts/before
curl https://api.fleetbase.io/v1/checkouts/before?gateway=cash&customer={{customer_id}}&cart={{cart_id}}&pickup=true \
  -H "Authorization: Bearer flb_live_…"
POST/v1/checkouts/capture

Capture checkout as order

Captures a checkout token and creates the corresponding order. Capture is idempotent: an already completed checkout returns its existing order, while a concurrent capture still in progress returns 409 so the client can retry safely.

Stripe checkouts are captured only after Fleetbase retrieves the server-linked PaymentIntent and verifies that it succeeded and matches the checkout amount, currency, customer, and live/test mode. An incomplete payment returns 402, a missing or mismatched PaymentIntent returns 422, and a temporary Stripe verification failure returns 502. Clients must confirm the PaymentIntent before calling this endpoint and must not send or trust a client-selected PaymentIntent ID during capture.

Because a contract run cannot complete a card payment, this example captures the cash pickup checkout created by Before Cash Pickup Checkout, which needs no provider payment; the unpaid Stripe checkout's 402 refusal is asserted by Capture Stripe checkout without payment.

Body parameters
tokenstringrequired

Checkout token returned by checkout initialization.

transactionDetailsobjectoptional

Optional gateway transaction details to store with the resulting transaction and order metadata.

notesstringoptional

Optional notes stored on the created order.

POST/v1/checkouts/capture
curl -X POST https://api.fleetbase.io/v1/checkouts/capture \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "{{cash_checkout_token}}"
}'
POST/v1/checkouts/capture

Capture Stripe checkout without payment

Documents the refusal contract for capturing a Stripe checkout whose PaymentIntent has not succeeded: the API answers 402 with "Stripe payment has not been completed." and creates no order. Client-supplied transaction details can never substitute for the provider's verified payment state.

Body parameters
tokenstringrequired

Checkout token of a Stripe checkout whose PaymentIntent has not succeeded.

POST/v1/checkouts/capture
curl -X POST https://api.fleetbase.io/v1/checkouts/capture \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "{{checkout_token}}"
}'
POST/v1/checkouts/capture-qpay

Capture QPay Callback

Processes a QPay checkout callback. Fleetbase verifies the checkout and gateway, checks the QPay invoice payment state, and creates the order when payment is confirmed.

Body parameters
checkoutstringrequired

Public checkout ID being confirmed by QPay.

respondbooleanoptional

Whether Fleetbase should return the payment check payload in the HTTP response.

testenumoptional

Sandbox-only test scenario to simulate. One of success, error.

POST/v1/checkouts/capture-qpay
curl -X POST https://api.fleetbase.io/v1/checkouts/capture-qpay \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "checkout": "{{checkout_id}}",
  "respond": true,
  "test": "success"
}'
GET/v1/checkouts/capture-qpay

Capture QPay Callback via GET

Processes a QPay checkout callback from query parameters. Sandbox requests can pass test to simulate success or failure.

Query parameters
checkoutstringoptional

Checkout value for this checkout request.

respondbooleanoptional

Respond value for this checkout request.

teststringoptional

Test value for this checkout request.

GET/v1/checkouts/capture-qpay
curl https://api.fleetbase.io/v1/checkouts/capture-qpay?checkout={{checkout_id}}&respond=true&test=success \
  -H "Authorization: Bearer flb_live_…"
GET/v1/checkouts/status

Get Checkout Status

Returns the status of a checkout by checkout ID or token.

Query parameters
checkoutstringoptional

Checkout value for this checkout request.

tokenstringoptional

Token used to authenticate or capture the checkout.

GET/v1/checkouts/status
curl https://api.fleetbase.io/v1/checkouts/status?checkout={{checkout_id}}&token={{checkout_token}} \
  -H "Authorization: Bearer flb_live_…"
POST/v1/checkouts/stripe-setup-intent

Create Stripe Setup Intent

Creates a Stripe SetupIntent for a storefront customer. The response includes Stripe client data for saving a payment method.

Body parameters
namestringrequired

Display name for the resource.

descriptionstringoptional

Human-readable description of the resource.

statusenumoptional

Lifecycle status to apply to the resource. One of active, inactive.

metastringoptional

Arbitrary metadata stored with the resource.

POST/v1/checkouts/stripe-setup-intent
curl -X POST https://api.fleetbase.io/v1/checkouts/stripe-setup-intent \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "{{customer_id}}"
}'
PUT/v1/checkouts/stripe-update-payment-intent

Update Stripe Payment Intent

Recalculates and updates an existing Stripe PaymentIntent for the current cart and checkout options. The response includes refreshed Stripe client data and a new checkout token.

Body parameters
customerstringrequired

Customer public ID. When Customer-Token is present it must identify the authenticated customer.

cartstringrequired

Cart public ID or unique identifier.

payment_intent_idstringrequired

Stripe PaymentIntent to update. paymentIntent and paymentIntentId are accepted aliases.

service_quotestringoptional

Delivery service quote public ID. serviceQuote is an accepted alias.

pickupbooleanoptional

Whether the order is a pickup order.

tipnumberoptional

Tip, as an amount or a percentage string such as 10%.

delivery_tipnumberoptional

Delivery tip, as an amount or a percentage string. deliveryTip is an accepted alias.

promo_codesarray of stringsoptional

Promo codes to apply, as an array or a comma separated string. promo_code and discount_code are accepted for a single code. Codes already applied to the cart are always included. The checkout is refused with 400 and promotions.rejected[] (\{ code, reason \}) when a code cannot be applied; the discount of the storefront's automatic promotions is applied without a code.

PUT/v1/checkouts/stripe-update-payment-intent
curl -X PUT https://api.fleetbase.io/v1/checkouts/stripe-update-payment-intent \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "{{customer_id}}",
  "cart": "{{cart_id}}",
  "service_quote": "{{service_quote_id}}",
  "payment_intent_id": "{{payment_intent_id}}",
  "pickup": false,
  "tip": 0,
  "delivery_tip": 0
}'
Checkout | Fleetbase