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 becomesPAID 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.
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: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 isorder.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.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.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 onlyPAID 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:
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 as4242 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 CAD
is 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 thePAYMENT 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 a200:
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.
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.