> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithsoap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# checkout.failed

> Event triggered when one payment attempt (charge) failed. Sent per charge, not per checkout; a declined attempt leaves the checkout open for a retry.

> [!WARNING]
>
> `checkout.failed` is off by default. It will not be delivered until you enable it in Dashboard → Developers. See [Receiving Webhooks](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/setup.md) for instructions.

## One Event Per Attempt, Not Per Checkout

Despite its name, `checkout.failed` does **not** mean the checkout failed. It reports that one **payment attempt** — one charge, identified by `data.charge.id` — failed. What happens to the checkout depends on `charge.from_status`:

* **`from_status: "created"`** — the attempt was declined while the customer was still in the checkout (a synchronous card decline, for example). The checkout stays open, the customer returns to the payment form, and their next submission is a new charge against the same checkout. See [One Checkout, Several Charges](https://docs.paywithsoap.com/api-reference/lifecycles.md#one-checkout-several-charges).
* **`from_status: "pending"`** or **`"succeeded"`** — the charge had already been accepted, and the customer had already left the checkout on a pending or success screen. The checkout is **not** reopened and the customer cannot retry inside it. If you want them to pay again, create a new checkout.

So within a single checkout you can receive `checkout.failed` for one charge and then `checkout.succeeded` for another. A customer whose first card is declined and who then pays with a different card or wallet produces exactly that pair, and it is expected.

A successful charge is reported by `checkout.succeeded`; the checkout-level terminal outcomes are `checkout.terminally_failed` and `checkout.expired`:

| Event | Meaning |
| - | - |
| [`checkout.succeeded`](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/checkout-succeeded) | A charge was approved. Credit the customer once, keyed on this charge's `data.charge.id`. |
| [`checkout.terminally_failed`](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/checkout-terminally-failed) | The checkout was blocked by geo, KYC or fraud checks and cannot be continued. No payment was taken. |
| [`checkout.expired`](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/checkout-expired) | The customer never completed the checkout before its deadline. |

`checkout.failed` is not one of them. Treat it as attempt-level history and never let it mark a checkout as failed.

> [!TIP]
>
> * Key every booking on `data.charge.id`. A `checkout.failed` for one charge must never undo a `checkout.succeeded` for a different charge in the same checkout, even if it arrives later — delivery is at-least-once and events can arrive out of order.
> * Dedupe on `event_id`; retries of the same event reuse it. See [Retries, Timeouts and Idempotency](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/webhooks.md#retries-timeouts-and-idempotency).
> * To confirm any charge's current state, read it back with [`GET /api/v1/charges/{id}`](https://docs.paywithsoap.com/api-reference/api-v1/charges/show).

## Payload Structure

```typescript theme={null}
interface WebhookEvent {
  event_id: string;
  data: {
    id: string; // id of the checkout you originally created
    line_items: Array<{
      product_id: string;
      quantity: number;
      total_amount_cents: number;
      product_name: string;
      product_url: string | null;
      product_price_cents: number;
      sku: string | null; // null when the product was created without a sku
    }>;
    line_items_total_amount_cents: number | null;
    type: "deposit" | "withdrawal"; // the checkout type — not the event type below
    charge: {
      id: string;
      amount_cents: number;
      transaction_type: "credit" | "debit";
      status: string;
      from_status: string;
      failure_code: string | null;
      failure_message: string | null;
    };
    customer: {
      id: string;
    };
    subscription: {
      id: string;
      interval: "day" | "week" | "month" | "year";
      interval_count: number;
      line_items: Array<{
        product_id: string;
        sku: string | null; // null when the product was created without a sku
        product_name: string;
        product_url: string | null;
        quantity: number;
        price_cents: number;
        total_amount_cents: number;
      }>;
      line_items_total_amount_cents: number | null;
    } | null; // null for non-subscription checkouts
  };
  type: "checkout.failed";
}
```

## Example Response

```json theme={null}
{
  "event_id": "ev_tDaWu5aTVa2kbvDjGe55rxZpaMEmVFWB",
  "data": {
    "id": "chk_twijxXgVFofj9mdnvzF7vhbJSZEhfUpC",
    "line_items": [],
    "line_items_total_amount_cents": null,
    "type": "deposit",
    "charge": {
      "id": "ch_yRZcCGouimTgbz4thtrfbj2mh3ZT6vnz",
      "amount_cents": 2500,
      "transaction_type": "credit",
      "status": "failed",
      "from_status": "created",
      "failure_code": "card_declined",
      "failure_message": "The card was declined by the issuing bank."
    },
    "customer": {
      "id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870"
    },
    "subscription": null
  },
  "type": "checkout.failed"
}
```

## Updating Your Internal Ledger

This event is triggered when one deposit or withdrawal attempt fails. For deposits, and for withdrawals you have not already debited, your ledger is usually unaffected — the customer may still complete the same checkout with a later attempt.

For withdrawals it can be the event that releases a hold, and missing it strands customer funds. Use `charge.from_status` to tell the two cases apart:

* **`from_status: "pending"`** — the payout was accepted for processing and then failed. Because the charge was pending rather than held immediately beforehand, Soap sends this event instead of [`checkout.release_hold`](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/checkout-release-hold). If you debited the customer on [`checkout.hold`](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/checkout-hold), **you must credit them back here.** See [the withdrawal hold lifecycle](https://docs.paywithsoap.com/api-reference/api-v1/checkouts/balance-withdrawal.md#every-way-a-hold-ends).
* **`from_status: "succeeded"`** — a settled charge was reversed after the fact. Track the `charge.id` state to reconcile these correctly.

> [!WARNING]
>
> This event is **off by default**. For withdrawals that means an accepted-then-failed payout produces no webhook at all unless you enable it in **Dashboard → Developers**, which is the most common way held funds go missing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.