Core concepts

The flow

1. Your server creates a checkout session with your API key.
2. You redirect the customer to the session's url, our hosted checkout.
3. The customer signs in, reviews the order and fees, confirms and pays. An escrow is created with your store as the seller.
4. We send webhooks as the escrow changes. When you receive escrow.funded, ship the order.
5. You submit the milestone with tracking details. The customer confirms receipt and the funds are released to your wallet (escrow.completed).

You make the offer

Creating a session is your offer to the customer, so the escrow skips the usual acceptance step and the customer goes straight to payment.

Customers need an account, not a password

Customers must be able to come back to approve delivery or open a dispute, so every escrow belongs to an account. Shoppers without one can choose Email me a secure link: we send a single-use link that expires after 30 minutes and create a verified account only when it is clicked. Existing accounts sign in normally.

Ids and reference codes

Escrows and milestones are identified by uuids; store them as strings. Each escrow also has a human-readable reference_code such as TR-20261125.482913.14999. Show it to customers: anyone can check it at /verify. Reference codes are not secrets and never grant access.

Fees are shown up front

The hosted checkout shows the platform fee breakdown before the customer commits. Fees are added on top of your amount, so amount is what you receive when every milestone is approved.

Money is a string

Every amount in the API is a decimal string with two decimal places ("149.99"), never a float.

Currency

USD only for now. Sessions in other currencies are rejected with a clear error rather than settled incorrectly.

Events are reliable, not ordered

Webhooks are sent at least once and may arrive out of order. Dedupe on the event id, never move an order backwards, and use GET /events to reconcile after downtime. See Webhooks.