checkout.failed

checkout.failed is off by default. It will not be delivered until you enable it in Dashboard → Developers. See Receiving Webhooks 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.
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`	A charge was approved. Credit the customer once, keyed on this charge’s `data.charge.id`.
`checkout.terminally_failed`	The checkout was blocked by geo, KYC or fraud checks and cannot be continued. No payment was taken.
`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.

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.
To confirm any charge’s current state, read it back with GET /api/v1/charges/{id}.

Payload Structure

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

{
  "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. If you debited the customer on checkout.hold, you must credit them back here. See the withdrawal hold lifecycle.
from_status: "succeeded" — a settled charge was reversed after the fact. Track the charge.id state to reconcile these correctly.

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.

API Documentation

API Endpoints

Webhooks

Testing

checkout.failed

One Event Per Attempt, Not Per Checkout

Payload Structure

Example Response

Updating Your Internal Ledger

​One Event Per Attempt, Not Per Checkout

​Payload Structure

​Example Response

​Updating Your Internal Ledger

One Event Per Attempt, Not Per Checkout

Payload Structure

Example Response

Updating Your Internal Ledger