Webhook event

`refund.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: refund.failed
The object it carries: the refund object
Subscribe with: refund.failed, refund.* 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_p998v2mnb5shbsq3z7pvb24f",
  "object": "event",
  "livemode": true,
  "created": "2026-10-12T10:13:40.000Z",
  "type": "refund.failed",
  "api_version": "2026-10-11",
  "data": {
    "object": {
      "id": "rf_z20ve49yz5hve8f0xsdchj2v",
      "object": "refund",
      "livemode": true,
      "created": "2026-10-12T10:00:00.000Z",
      "updated": "2026-10-12T10:13:40.000Z",
      "status": "failed",
      "pending_reason": null,
      "order": "ord_0zymngngvf12b8b2cra7tb8e",
      "payment": "pay_2pe50hae6w2jk4sp1rcq5pae",
      "amount": "5.00",
      "currency": "USD",
      "reason": "requested_by_customer",
      "note": "One bag arrived damaged",
      "rate_basis": "order_rate",
      "deduct_network_fee": false,
      "source": {
        "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
        "asset": "base:usdc",
        "amount": "5.000000"
      },
      "destination": {
        "address": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
        "asset": "ethereum:usdc",
        "network": "ethereum",
        "supplied_by": "payer_claim",
        "saved_address": null
      },
      "address_claim": {
        "sent_to": "jane@example.com",
        "sent_at": "2026-10-12T09:40:00.000Z",
        "claimed_at": "2026-10-12T10:00:00.000Z",
        "expires_at": "2026-10-26T09:40:00.000Z"
      },
      "approvable_at": null,
      "delivery": {
        "rail": "relay",
        "amount_estimated": "4.930000",
        "route_fee": {
          "amount": "0.07",
          "currency": "USD"
        },
        "fee_bearer": "recipient"
      },
      "network_fee": null,
      "requested_by": {
        "type": "api_key",
        "id": "key_6e3gg2c6ea176xxdek2nar6v"
      },
      "approved_by": "mem_ceh1wpzdrpk13cnpcjy9w0fa",
      "approval_url": null,
      "approval_expires_at": "2026-10-19T10:00: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": {}
    },
    "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 refund.failed
Field	In this example
`id`	`"rf_z20ve49yz5hve8f0xsdchj2v"`
`object`	`"refund"`
`livemode`	`true`
`created`	`"2026-10-12T10:00:00.000Z"`
`updated`	`"2026-10-12T10:13:40.000Z"`
`status`	`"failed"`
`pending_reason`	`null`
`order`	`"ord_0zymngngvf12b8b2cra7tb8e"`
`payment`	`"pay_2pe50hae6w2jk4sp1rcq5pae"`
`amount`	`"5.00"`
`currency`	`"USD"`
`reason`	`"requested_by_customer"`
`note`	`"One bag arrived damaged"`
`rate_basis`	`"order_rate"`
`deduct_network_fee`	`false`
`source`	An object with `wallet`, `asset`, `amount`
`destination`	An object with `address`, `asset`, `network`, `supplied_by`, `saved_address`
`address_claim`	An object with `sent_to`, `sent_at`, `claimed_at`, `expires_at`
`approvable_at`	`null`
`delivery`	An object with `rail`, `amount_estimated`, `route_fee`, `fee_bearer`
`network_fee`	`null`
`requested_by`	An object with `type`, `id`
`approved_by`	`"mem_ceh1wpzdrpk13cnpcjy9w0fa"`
`approval_url`	`null`
`approval_expires_at`	`"2026-10-19T10:00: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 no fields

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

Endpoints behind it

Calls that change refunds. 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.