# Statuses and escrow (/docs/payments/statuses-and-escrow)

Two moments matter for every sale, and they aren't always the same moment:

1. **The buyer paid.** The money has arrived and the order exists. Fulfil it. This is the [`checkout.paid`](/docs/webhooks/events) webhook.
2. **You've been paid.** Swop has released the money to your wallet. Book the revenue. This is the [`payout.released`](/docs/webhooks/events) webhook.

## When is money held (escrow)? [#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 |

{/* Checked 2026-11-16: production sets no MARKETPLACE_ESCROW_AUTO_RELEASE_DAYS (api task definition), so the code default of 30 days applies (settlementRelease.service.js). Re-check before changing the number. */}

### How a held payment is released [#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 [#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 [#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 |

<Callout type="warn">
`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.
</Callout>

## Order statuses [#order-statuses]

What [`GET /orders`](/docs/api-reference/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.
