PAID when it’s covered.
Card payments don’t belong here. They go through Stripe: see
Accept payments with Stripe.
For the transaction object, every kind and source, and the full list of
refusals, see Transactions.
Both routes in this guide take the
x-api-key header alone. Call them from
your server or the business’s own tools, never from a client’s browser.How it works
- Read the order. Check its
status, its currency and what it still owes. - Record the money.
POST /orders/{orderId}/transactionswith akind, asource, the amount and anidempotencyKey. - Check the result.
201is a new recording,200is a replay of one you already made. When the ledger covers the order’s total, the order isPAID. - Reconcile later.
GET /transactionsreads the ledger back.
Step 1: Read the order
GET /v1/projects/{projectId}/orders/{orderId} returns the figures you need:
What the order still owes is
total.amount - amountPaid.amount - (amountComped?.amount ?? 0). For a total of 9000 with 4500 paid, the
balance is 4500, which is $45.00.
A CANCELLED order takes no payment or comp. The recording is a 422,
and nothing is written:
PAID order isn’t checked. A payment on it is recorded, and
amountPaid rises past total. Nothing in the API can give that money back:
refunds are made in the MarketBox dashboard. So read the order first, and
refuse to take money against one that’s already settled.
Step 2: Record the money
Pick thekind and source from what happened:
amount.amountis in minor units.4500is $45.00.amount.currencymust be the order’s currency. An order’s currency never changes, and the route doesn’t convert.noteis free text for the business’s team, up to 500 characters.clientIdis optional. Leave it out to use the order’s client.
SUCCEEDED at once. There is nothing to poll.
Send an idempotency key
A cash recording is the request you least want to make twice. Make anidempotencyKey (a UUID is fine) when someone presses Record,
store it with the payment on your side, and send the same key on every retry.
- The first call records the money and returns
201, withreplayed: false. - The same key on the same order returns the row the first call made, as
200withreplayed: true. Nothing is recorded again.
201: a 200 is money
you already counted.
A replay returns the original row as it was. The server doesn’t compare
bodies, so a retry with the same key and a different amount still returns
the first amount. A retry must still be a valid request, though: the body,
the order, the currency and any clientId are checked before the key, so a
retry that fails one of those gets the 400 or 404, not the replay. Use a new key for a new payment, and never reuse one across
two payments on the same order.
Waive what’s left with a comp
To waive a balance, record anADJUSTMENT with source: COMP for the amount
still owed, with a reason:
amountComped, not amountPaid, so reports keep money waived
apart from money received.
Comp last. A card checkout charges total minus amountPaid, and
ignores amountComped. So if you comp part of an order and then send the
client to pay by card, they’re charged for the comped part too. Take the
card payment first, then comp what’s left. Record why the charge was waived, not that it was:
the row already says that.
A comp with no reason is refused, and nothing is recorded:
reason of only spaces is a 400 BAD_REQUEST, A COMP transaction needs a reason.
Two other rows are accepted but rarely what you want:
PAYMENTwithsource: COMPcounts towardamountPaid, as if the waived money were received. It needs areasontoo, like every comp. UseADJUSTMENTinstead, so your cash figures stay true.ADJUSTMENTwithCASHorEXTERNALis a note in the ledger. It doesn’t move the balance or settle the order.
Step 3: Check the result
The order becomes PAID
When amountPaid plus amountComped covers total, a DRAFT or PENDING
order becomes PAID in the same write as the recording. Two fields are
stamped on it then:
paymentMethod:CASH,EXTERNALorCOMP, orMIXEDwhen more than one source paid.settledAt: when the recording that completed it was made.
ADJUSTMENT with CASH or
EXTERNAL never settles an order.
You can’t ask for PAID yourself. POST /orders/{orderId}/status with
PAID is 409 ORDER_NOT_SETTLED. See
Order lifecycle after checkout.
What PAID unlocks
- A signed-in client’s package credits. A client can see and book a
package only once its order is
PAID. See Book a client’s package credit. So when a client pays cash for a package, record it before they try to book. - Nothing else. Single bookings, and package bookings made with your API
key, don’t wait for
PAID. See Order lifecycle after checkout.
A recorded order can’t be deleted
Once an order holds any recorded transaction, including a comp or an adjustment,DELETE /orders/{orderId} refuses it with
409 ORDER_NOT_DELETABLE. Cancel it instead. See
Cancel or delete.
When a recording is refused
Nothing is recorded on any of these. The currency doesn’t match the order’s:note.
The order changed while the payment was being recorded:
idempotencyKey. The key makes sure the retry can’t
record twice.
409 TRANSACTION_IDEMPOTENCY_RECORD_MISSING is the exception. The key was
used, but its row can’t be read back. It’s terminal: retrying can never
succeed. Don’t retry, and don’t record the payment again under a new key.
Read the order’s ledger (see Reconcile the ledger)
and contact support with the requestId.
The rest are in
Refusals.
A recording was wrong
The ledger is append-only. No route edits or deletes a row, andkind: REFUND is refused. To correct a mistake:
- Too little recorded: record the difference as another payment.
- Too much recorded, or the wrong order: refund or correct it in the MarketBox dashboard. The public API has no refund route.
Reconcile the ledger
GET /v1/projects/{projectId}/transactions reads the ledger, newest first.
It takes one of orderId, clientId or status, with an optional
startDate and endDate.
The three filters don’t combine. Only one takes effect, in the order
orderId, clientId, status, and the rest are ignored without an error.
So orderId with status=SUCCEEDED returns every row on the order. Send one
filter, and filter the rest on your side.
To total a day’s cash and transfers, list by status=SUCCEEDED for the day,
then count by source on your side:
startDateis inclusive andendDateis exclusive. Pass the next day’s start asendDate. Both are UTC instants, so turn the business’s local midnight into one first.- Send both with milliseconds, as
.000Z. The bounds are compared with each row’s timestamp as text, so…T05:00:00Zlands up to a second off. - Page with
cursoruntilnextCursorisnull. A page can hold fewer thanlimitrows before the end, so never stop on a short page. See Pagination.
source:
- Count only
SUCCEEDEDrows. APENDINGStripe row is a payment started, not money received. When you list byorderIdorclientId, every status comes back. - Leave out
ADJUSTMENTrows. AnADJUSTMENTwithsource: COMPis money waived. Report it apart from what you collected. - Leave out
CREDIT_REDEMPTIONandCREDIT_REVERSAL. They track package sessions, not money. - Report a
PAYMENTwithsource: COMPapart fromCASH, even though it counts as paid.
GET /orders?paymentMethod=CASH is quicker, but it misses MIXED orders and
orders not yet PAID. A cash order you later cancelled still appears, with
status: "CANCELLED". See
Summing the ledger.