Statuses and escrow
The difference between "the buyer paid" and "you've been paid", and every status you'll see.
Two moments matter for every sale, and they aren't always the same moment:
- The buyer paid. The money has arrived and the order exists. Fulfil it. This is the
checkout.paidwebhook. - You've been paid. Swop has released the money to your wallet. Book the revenue. This is the
payout.releasedwebhook.
When is money held (escrow)?
Escrow means Swop holds the buyer's payment until the order is delivered, then releases it to you. It protects buyers of physical goods they haven't seen yet, which is also why it helps you sell: a customer who has never bought from your site can pay knowing the money isn't sent to you until their order arrives.
Escrow works the same way for USDC and card payments.
| Order | Payout policy (settlement.policy) | When you're paid |
|---|---|---|
| Contains a physical item, sold online | escrow_on_receipt | When the buyer confirms they received it, or automatically 30 days after it's marked delivered |
| Digital items only | direct | Straight away, as part of settlement |
| In-person sale (tap to pay at a counter) | direct | Straight away |
How a held payment is released
- The buyer confirms receipt. Released straight away. Confirming needs a Swop account: buyers do it from the order in the Swop app.
- The buyer does nothing. Released automatically 30 days after the order is marked delivered.
- The buyer reports a problem. Opening a dispute pauses the release, so the payment stays held while it's reviewed. Buyers can open one from the private order link in their receipt email, with no Swop account.
Mark shipments as shipped and delivered on the order in the Swop app. The 30-day clock starts only once an order is marked delivered, so an order that's never marked delivered stays held until the buyer confirms it.
What buyers see at checkout
Swop's checkout tells buyers how this works before they pay, so you don't have to explain it on your site:
- Orders that are held show Protected by Swop escrow: Swop holds the payment, not the seller, until the order arrives, with the release rules above. This appears for card and for USDC.
- Paying with crypto also explains that the buyer pays from their own wallet, that crypto payments are final once sent (refunds come back through Swop, not a bank), and that their receipt links to their order, where they can follow it or report a problem.
- Digital-only orders say the seller is paid right away, and make no escrow claim.
Checkout statuses
What GET /checkout-intents/{intentId} returns in status:
| Status | Meaning |
|---|---|
active | Created and waiting for the buyer |
pending_payment | A payment has started but isn't final yet |
paid | The buyer's money has arrived; the order exists |
settled | Swop has finished processing the payment |
conversion_failed | Paid, but a currency conversion step after payment failed. Swop has the money. |
settlement_failed | Paid, but a settlement step failed. Swop has the money. |
refunding | A refund is in progress |
refunded | Refunded to the buyer |
expired | Passed expiresAt without payment |
cancelled | Cancelled before payment |
conversion_failed and settlement_failed mean the buyer has paid. Never show "you weren't charged" for these. Tell the buyer Swop has their payment and support will complete the order or refund them.
Order statuses
What GET /orders and webhooks return.
| Field | Values |
|---|---|
status | created, paid, fulfilling, completed, cancelled, failed |
payment.status | pending, completed, failed, refunded, cancelled |
settlement.status (your payout) | pending, held, release_pending, releasing, released, failed, refunded |
fulfillment.status | not_required, pending, processing, shipped, out_for_delivery, delivered, receipt_confirmed, cancelled |
settlement.status: released is the moment you've been paid. That's when payout.released fires.