Skip to main content
This guide walks you through taking real payments in a custom booking flow. A client books, you charge their card with Stripe, and the order is marked paid — all without card details ever touching your server. It builds on Build a booking flow: you already have an API key, the backend-for-frontend (BFF) pattern, and can create orders. Here you add the payment step. For cash, bank transfers and comps, which don’t go through Stripe, see Record offline payments.

How payments work

MarketBox charges cards through Stripe Connect using direct charges: the charge is created on the business’s own connected Stripe account, and the business is the merchant of record. Card data goes straight from the client’s browser to Stripe using Stripe’s Payment Element, so your servers never see or store it (this keeps you at the lightest PCI compliance level, SAQ-A). The money flow has one rule worth memorizing: an order becomes PAID only when Stripe confirms the charge through a webhook — never from the browser’s confirmation response. That webhook goes from Stripe to MarketBox, because MarketBox creates the PaymentIntent on the business’s connected account. The public API sends no webhooks to you, so you poll the order (Step 4). You mark nothing as paid yourself; you wait for MarketBox to. Asking POST .../orders/{orderId}/status for PAID is refused with 409 ORDER_NOT_SETTLED.
Holding time during checkout? Convert the hold from your server once your poll sees PAID. Convert doesn’t check payment, so you can convert as soon as stripe.confirmPayment resolves instead, but that books before the charge is confirmed: keep polling and reconcile any order that never reaches PAID. Don’t do that for a package hold in a client flow: a client’s package credits book only once the order is PAID. Convert is idempotent per reservationId, so a retry is safe. See Hold slots during checkout.
The card is saved to the client. When the order’s client has an email on file, the PaymentIntent is created with setup_future_usage: off_session, so the card is saved to that client’s record in Stripe for future bookings. Tell the client at checkout that their card will be saved. An intent reused from an earlier call is updated to save the card too, provided it has not been confirmed yet.

Prerequisites

1

The business connects its Stripe account

Before you can charge, a project admin connects the business’s Stripe account on the project’s Payments settings page in the MarketBox dashboard. This is a one-time action per business, done through Stripe’s hosted onboarding.
Connecting is not enough on its own — Stripe must have charges enabled on the account. With Standard Connect the business completes Stripe’s own onboarding (business profile, and identity details such as a tax ID) until Stripe activates charges. Until then, creating a PaymentIntent returns 409 CONFLICT (the project has no Stripe account connected, or isn’t yet cleared to take charges). The business owner completes this in their own Stripe dashboard; the platform cannot fill it in for them.
2

Get your Stripe browser values

Direct charges need two public values in the browser:
A publishable key is meant to be public — it can only do safe client-side work (confirming a PaymentIntent that already has a client_secret). For direct charges you use MarketBox’s one platform publishable key and target the individual business with its account id (stripeAccount), not a per-business key.
3

Install Stripe.js

Configure the keys

Add the two public values to your browser config, and keep your API key server-only as always:
Initialize Stripe.js once, binding the platform key to the connected account:

Step 1 — Start from an order with a balance

You charge an order, not individual items. Create the order (or reach an existing one) so it has a positive balance to collect. See Orders for the full lifecycle; the amount you’ll charge is order.total − order.amountPaid − order.amountComped. Treat amountComped as zero when it’s absent.
The order must be in DRAFT or PENDING status, and the balance must be greater than zero. Amounts are integer minor units (cents): 4500 means $45.00.
An order already paid or comped in full is refused:

Step 2 — Create the PaymentIntent from your BFF

Add a BFF route that asks MarketBox to create the PaymentIntent. MarketBox creates it on the connected account, records a pending transaction, and returns the client secret your browser needs. The API key stays on the server.
A successful response carries the client secret:
Calling this endpoint again for the same order reuses the existing pending PaymentIntent instead of creating a second one, so it’s safe to retry. An order has at most one open card payment. The intent is reused only while it is for the amount owed now. If the amount owed has changed, for example after you add an item, the old intent is canceled and you get a new clientSecret for the new amount. Mount the Payment Element with the clientSecret from the latest call. Still, request it once per checkout on the client (see the ref guard below).
While a card payment on the order is already moving, the call is refused. That happens when the intent is processing, or a saved-card charge on the order is in flight:
Don’t start another payment. Poll the order, as in Step 4, until it’s PAID or the transaction leaves PENDING.

Step 3 — Collect the card with the Payment Element

Fetch the client secret, mount Stripe’s Payment Element, and confirm. The card is entered inside Stripe’s iframe and sent directly to Stripe.

Step 4 — Wait for the webhook to mark the order paid

The browser’s “succeeded” result means the card cleared — but the order is only PAID once Stripe’s webhook reaches MarketBox and the ledger is finalized. That usually takes a couple of seconds. Poll the order until it flips. Add a BFF route to read the order:
And poll it from the client:
Never treat the browser’s confirmation result as proof of payment. It can be lost, delayed, or spoofed. The order status (driven by the webhook) is the source of truth for whether money moved.
A client who closes the tab before the poll ends still pays. Keep the orderId on your server and check the order again later. See Tracking state without webhooks.

Test it

The API charges in Stripe live mode. There is no test mode, and Stripe’s test cards, such as 4242 4242 4242 4242, are declined. To check your flow end to end, pay a small real amount in a project you control:
1

Pay with a real card

Use your own card, on an order above Stripe’s minimum charge (below). The business refunds it afterwards in the MarketBox dashboard: the API has no refund route.
2

Confirm the order is paid

Poll the order (Step 4) — it should flip to PAID within a few seconds, with amountPaid equal to total.
3

Inspect the ledger (optional)

GET /v1/projects/{projectId}/transactions?orderId={orderId} shows a PAYMENT / STRIPE / SUCCEEDED transaction for the charge.
Minimum charge. Stripe rejects amounts below roughly **$0.50 USD equivalent**. Mind currency conversion — for example `$0.50 CADis under the USD floor and will fail. There is no way to charge a$0` balance; skip the payment step when nothing is owed.

Packages work the same way

A package order (buying a block of session credits) charges exactly like a single order — the amount is the package’s price, and the same Payment Element flow applies. After payment, the order’s ledger shows the PAYMENT plus a CREDIT_REDEMPTION transaction for each session booked against the package, so you can see both the money in and the credits drawn down. A cancelled session whose credit goes back to the package adds a CREDIT_REVERSAL that points at its redemption through relatedTransactionId. Credit actually used is redemptions minus reversals. Neither is money: both have source: "PACKAGE_CREDIT".

Show the card a client last paid with

Once a card payment settles, MarketBox records a small snapshot of the card on the client’s profile. It’s there for one purpose: so you can show a returning client something like “You last paid with Visa ending 4242” without building your own card store. Read it from the client profile. Onboarding is idempotent, so calling it again for an already-onboarded client simply returns their current profile with a 200:
The two fields to look at:
Both fields are optional. They’re absent for a client who has never paid by card — a brand-new client, or one who has only ever paid by cash or been comped. Always guard before rendering.
This is for display, not for deciding what to charge. lastPayment is a derived, best-effort snapshot, and Stripe remains the source of truth for what cards a client actually has. It is written from Stripe’s charge.succeeded webhook, so it can lag a payment by a second or two, and in rare cases (a webhook that never lands and is recovered by reconciliation instead) it may not update at all until the client’s next payment. Don’t gate a checkout on it, don’t reconcile against it, and don’t infer from it that a card is still valid or chargeable.
There is no public endpoint to charge a saved card. Every payment in a custom booking flow goes through the Payment Element (Steps 2–3) — which is what keeps you at SAQ-A. lastPayment tells you what the client used last; it does not let you re-use it.

Reference

Endpoints used in this guide

Configuration

Errors and edge cases

Security checklist

MARKETBOX_API_KEY is server-only — never NEXT_PUBLIC_.
Card data is collected only by Stripe’s Payment Element — never posted to your server.
Order status (not the browser result) is what you treat as proof of payment.
The publishable key and account id are the only Stripe values in the browser — both are public and safe.
lastPayment is treated as display-only — never as proof a card is valid or chargeable.