---
title: "A recurring charge failed"
method: POST
path: "subscription.payment.failed"
tags: ["Webhooks"]
---

# A recurring charge failed

`POST subscription.payment.failed` (webhook)

Sent when a recurring charge fails to settle. `payload.data` is the
`Payment` record; see `payload.data.failureReason`.
`payload.entityId` is the parent subscription.

## Payload

- SubscriptionPaymentFailedEvent — The wrapper delivered for every webhook event. `payload.data` holds the event-specific resource — a `Subscription` or a `Payment`.
  - `id` string, uuid, required — Unique id of this event (UUIDv7). Stable across redeliveries — delivery is at-least-once and the same `id` is replayed on retry, so use it to dedupe.
  - `timestamp` string, date-time, required — When the event was produced (ISO-8601 UTC).
  - `entityId` string, uuid, required — The subscription this event concerns. Always the subscription id, even for payment events — which route to their parent subscription.
  - `version` integer, required — Monotonically increasing per subscription. Use it to order a subscription's events and discard stale redeliveries.
  - `payload` object, required — The inner event body. The `data` property — typed per event family — carries the affected resource.
    - `eventType` 'subscription.payment.failed', required — Identifies the event — one of the types listed under Webhooks.
    - `resourceType` 'subscription', required — The routed resource kind. Always `subscription`.
    - `entityId` string, uuid, required — The subscription id this event routes to (same as the envelope `entityId`).
    - `data` Payment, required — A single recurring-billing charge. One record per attempted cycle; starts as `PENDING` and settles to `SUCCEEDED` or `FAILED`.
      - `id` string, uuid, required
      - `subscriptionId` string, uuid, required
      - `billedAmount` Price, required — Monetary amount. `amount` is a decimal string. `asset` is an ISO 4217 code for fiat or an uppercase stablecoin symbol — e.g. `USD`, `EUR`, `USDC`, `USDT`.
        - `amount` string, required
        - `asset` string, required
      - `paidAmount` Price, required — Monetary amount. `amount` is a decimal string. `asset` is an ISO 4217 code for fiat or an uppercase stablecoin symbol — e.g. `USD`, `EUR`, `USDC`, `USDT`.
        - `amount` string, required
        - `asset` string, required
      - `balance` PaymentBalance — Balance view of a succeeded payment. `asset` is the fiat code for a conversion, or the paid stablecoin for "same crypto as paid". `feeTotal == feeBase + feeProvider + feeNetwork`.
        - `asset` string, required — AnyAsset code (fiat or stablecoin).
        - `amount` string, required — Gross credited, in `asset`.
        - `feeBase` string, required
        - `feeProvider` string, required
        - `feeNetwork` string, required
        - `feeTotal` string, required
      - `status` 'PENDING' | 'SUCCEEDED' | 'FAILED', required — `PENDING` — charge initiated, not yet settled. `SUCCEEDED` — charge settled successfully. `FAILED` — charge did not settle.
      - `paidAt` integer — Unix epoch seconds.
      - `failure` PaymentFailure — Failure details. Null unless `status` is `FAILED`.
        - `reason` string, required — Classification of the failure. One of a fixed set of values: `INSUFFICIENT_BALANCE`, `INSUFFICIENT_ALLOWANCE`, `ON_CHAIN_REVERT`, `DROPPED_BY_BLOCKCHAIN`, `REJECTED_BY_COMPLIANCE`, `PROVIDER_ERROR`, `UNKNOWN`.
      - `cycleNumber` integer, required — Which billing cycle this payment belongs to.
      - `createdAt` integer, required — Unix epoch seconds.

## Acknowledgement `2XX`

Return any 2xx status to acknowledge receipt. Any other response
(or a timeout) is treated as a delivery failure and retried.

---

[API](https://skmtc.dev/confirmo/apis/confirmo-subscribe-api.md) · [All operations](https://skmtc.dev/confirmo/apis/confirmo-subscribe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/confirmo/confirmo-subscribe-api/revisions/105015030952/schema)