Payout statuses

Every payout endpoint returns the merchant view of a payout.

{
  "payout_id": "po_9f3c1d7b2a8e4c15d0b6a291",
  "status": "paid",
  "status_version": 4,
  "amount": "25.00",
  "fee": "0.50",
  "total_reserved": "25.50",
  "currency": "USD",
  "funds_released": false,
  "merchant_reference": "refund-ORD-10231",
  "customer_id": null,
  "delivery": "link",
  "source": "api",
  "case_reference": null,
  "selected_method": "cashapp",
  "safe_reason": null,
  "receipt_reference": "rcpt_4f2a8c1d9b3e5a7c6d0f",
  "created_at": "2026-09-28T09:14:22Z",
  "accepted_at": "2026-09-28T09:31:07Z",
  "payout_expires_at": "2026-10-05T09:14:22Z",
  "updated_at": "2026-09-28T09:33:41Z"
}

What you will never receive

The recipient's address, or any transaction identifier. receipt_reference is the opaque reference for support conversations. This is by construction, not a filter — asking for the address in a different way will not produce it.

📊 Statuses

Status	Meaning	Money
awaiting_choice	Created; the recipient has not confirmed	Held
processing	Confirmed; the transfer is under way, or queued (see safe_reason)	Held
review_required	Held for a manual check	Held
paid	Sent and verified	Spent
cancelled	You cancelled it	Returned
expired	Nobody claimed it before the deadline	Returned
failed	It could not be sent	Returned

funds_released: true means the money is back in your balance. Read that field rather than inferring it from the status.

An awaiting_choice payout expires at payout_expires_at: 7 days after creation for link delivery, 24 hours for redirect delivery. Once the recipient confirms, the deadline no longer applies.

🏷️ safe_reason

A short, machine-readable note on the current status. It is often null.

Value	Meaning
awaiting_float	With processing: the recipient has confirmed and the payout is queued on our side. It is sent automatically — nothing for you or the recipient to do
cancelled	With cancelled: you cancelled it
claim_deadline_passed	With expired: nobody claimed it in time

Other values may appear, mostly with review_required and failed. Treat them as informational: drive your logic from status and funds_released, never from safe_reason. Quote the receipt_reference if you need to ask us about one.

🔢 status_version

status_version increases on every change. If you store status, ignore anything that arrives with a version you have already seen: responses to overlapping requests can arrive out of order.

if (incoming.status_version <= stored.status_version) {
  return; // stale or duplicate — ignore
}