Webhook event

`payout.failed`

The transaction failed on chain or the route failed and the funds are back in the merchant wallet. The reserve is released. Failure codes are in the failure codes of money out.

Type: payout.failed
The object it carries: the payout object
Subscribe with: payout.failed, payout.* or *

Example payload

The body of the request your endpoint receives, shown here over several lines. On the wire it is compact JSON; check its signature over the bytes exactly as they arrive.

Example payload

{
  "id": "evt_8a01cjb5ewcnnkc98aw6c52s",
  "object": "event",
  "livemode": true,
  "created": "2026-10-12T10:13:40.000Z",
  "type": "payout.failed",
  "api_version": "2026-10-11",
  "data": {
    "object": {
      "id": "po_351ggq5kz6kxwpfrhp5qh3b0",
      "object": "payout",
      "livemode": true,
      "created": "2026-10-12T09:30:00.000Z",
      "updated": "2026-10-12T10:13:40.000Z",
      "kind": "payout",
      "status": "failed",
      "pending_reason": null,
      "batch": null,
      "source": {
        "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
        "asset": "base:usdc",
        "amount": "250.000000"
      },
      "destination": {
        "saved_address": "dst_92jw0br3z1bzkk45ddjqcm6q",
        "address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
        "network": "base",
        "asset": "base:usdc"
      },
      "delivery": {
        "rail": "direct",
        "amount_estimated": "250.000000",
        "route_fee": null,
        "fee_bearer": null
      },
      "value": {
        "amount": "250.00",
        "currency": "USD"
      },
      "description": "October green beans",
      "reference": "PO-2210",
      "network_fee": null,
      "requested_by": {
        "type": "api_key",
        "id": "key_6e3gg2c6ea176xxdek2nar6v"
      },
      "approved_by": "mem_ceh1wpzdrpk13cnpcjy9w0fa",
      "approval_url": null,
      "approval_expires_at": "2026-10-19T09:30:00.000Z",
      "transaction_hash": "0x1f3cb18e896256d7d6bb8c11a6ec71f005c75de05e39beae5d93bbd1e2c8b7a9",
      "failure_code": "transaction_reverted",
      "cancellation_reason": null,
      "approved_at": "2026-10-12T10:12:00.000Z",
      "sent_at": "2026-10-12T10:12:09.000Z",
      "confirmed_at": null,
      "metadata": {
        "supplier_id": "s_19"
      }
    },
    "previous_attributes": {
      "status": "sent",
      "failure_code": null
    }
  },
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "pending_webhooks": 1
}

Fields of data.object

Fields of data.object in payout.failed
Field	In this example
`id`	`"po_351ggq5kz6kxwpfrhp5qh3b0"`
`object`	`"payout"`
`livemode`	`true`
`created`	`"2026-10-12T09:30:00.000Z"`
`updated`	`"2026-10-12T10:13:40.000Z"`
`kind`	`"payout"`
`status`	`"failed"`
`pending_reason`	`null`
`batch`	`null`
`source`	An object with `wallet`, `asset`, `amount`
`destination`	An object with `saved_address`, `address`, `network`, `asset`
`delivery`	An object with `rail`, `amount_estimated`, `route_fee`, `fee_bearer`
`value`	An object with `amount`, `currency`
`description`	`"October green beans"`
`reference`	`"PO-2210"`
`network_fee`	`null`
`requested_by`	An object with `type`, `id`
`approved_by`	`"mem_ceh1wpzdrpk13cnpcjy9w0fa"`
`approval_url`	`null`
`approval_expires_at`	`"2026-10-19T09:30:00.000Z"`
`transaction_hash`	`"0x1f3cb18e896256d7d6bb8c11a6ec71f005c75de05e39beae5d93bbd1e2c8b7a9"`
`failure_code`	`"transaction_reverted"`
`cancellation_reason`	`null`
`approved_at`	`"2026-10-12T10:12:00.000Z"`
`sent_at`	`"2026-10-12T10:12:09.000Z"`
`confirmed_at`	`null`
`metadata`	An object with `supplier_id`

What each field means is on the page of the payout object. data.previous_attributes holds the old values of exactly the fields that changed: here status, failure_code.

Endpoints behind it

Calls that change payouts. An event is also sent when a payer, the network, a timer or a person in the dashboard causes the change; the sentence above says which.