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.
| 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 after a waiting period once 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 |
Mark shipments as shipped and delivered in the Swop app so the release clock can start.
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.