docs
Get startedTroubleshootingPaymentsWebhooksAgent paymentsSwop MCPOviIdentity (swop.id)SwivyRPC (preview)API reference

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:

  1. The buyer paid. The money has arrived and the order exists. Fulfil it. This is the checkout.paid webhook.
  2. You've been paid. Swop has released the money to your wallet. Book the revenue. This is the payout.released webhook.

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.

OrderPayout policy (settlement.policy)When you're paid
Contains a physical item, sold onlineescrow_on_receiptWhen the buyer confirms they received it, or automatically 30 days after it's marked delivered
Digital items onlydirectStraight away, as part of settlement
In-person sale (tap to pay at a counter)directStraight 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:

StatusMeaning
activeCreated and waiting for the buyer
pending_paymentA payment has started but isn't final yet
paidThe buyer's money has arrived; the order exists
settledSwop has finished processing the payment
conversion_failedPaid, but a currency conversion step after payment failed. Swop has the money.
settlement_failedPaid, but a settlement step failed. Swop has the money.
refundingA refund is in progress
refundedRefunded to the buyer
expiredPassed expiresAt without payment
cancelledCancelled 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.

FieldValues
statuscreated, paid, fulfilling, completed, cancelled, failed
payment.statuspending, completed, failed, refunded, cancelled
settlement.status (your payout)pending, held, release_pending, releasing, released, failed, refunded
fulfillment.statusnot_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.

On this page