payment.failed

{
  "event": "payment.failed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "paymentContext": {
      "reason": "recurring_billing",
      "paymentLinkId": null,
      "recovery": null
    },
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043",
    "customerId": "user_123",
    "subscriptionId": "sub_1a2b3c4d",
    "provider": "stripe",
    "paymentMethod": "card",
    "subPaymentMethod": null,
    "failureCode": "card_declined",
    "failureMessage": "Your card was declined.",
    "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
  }
}

{
  "event": "payment.failed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "paymentContext": {
      "reason": "recurring_billing",
      "paymentLinkId": null,
      "recovery": null
    },
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043",
    "customerId": "user_123",
    "subscriptionId": "sub_1a2b3c4d",
    "provider": "stripe",
    "paymentMethod": "card",
    "subPaymentMethod": null,
    "failureCode": "card_declined",
    "failureMessage": "Your card was declined.",
    "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
  }
}

paymentContext

The original reason for a charge and how this attempt was initiated. Recovery never replaces the original reason. Context can be null when it was not captured, including retries of historical invoices.

Fields and payment reasons

`reason`

stringThe original reason, preserved across payment attempts.

`paymentLinkId`

string | nullThe public payment link ID, or null when the charge did not originate from a payment link. This is independent of the reason and recovery method.

`recovery`

object | nullNull when the charge does not recover a subscription. payment_recovery identifies a manually recovered overdue subscription, a return after cancellation for non-payment, or a retry of a failed subscription resume. Initial checkout and one-time payment retries are not recovery. dunning_retry identifies an automatic charge retry, not a webhook delivery retry.

`recovery.attempt`

integerThe charge retry position in the dunning schedule, starting at 1. The original failed charge is not a retry. Present only for dunning_retry.

`recovery.maxAttempts`

integerThe total automatic retries applicable to this charge when the attempt began. It is not the number of retries remaining. Present only for dunning_retry.

reason	When it applies
`first_subscription_payment`	The initial subscription payment.
`trial_conversion`	The payment when a free trial ends.
`recurring_billing`	A subscription renewal.
`plan_change`	A charge caused by a plan change.
`reactivation`	A charge to reactivate a canceled subscription.
`subscription_resume`	A charge to resume a paused subscription.
`one_time_payment`	A one-time payment, including payment links.
`overage`	A charge for usage beyond the included allowance.
`adjustment`	A charge from an adjustment invoice.

Initial attempt

The original charge attempt, before recovery.

Initial attempt

{
  "event": "payment.failed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "paymentContext": {
      "reason": "recurring_billing",
      "paymentLinkId": null,
      "recovery": null
    },
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043",
    "customerId": "user_123",
    "subscriptionId": "sub_1a2b3c4d",
    "provider": "stripe",
    "paymentMethod": "card",
    "subPaymentMethod": null,
    "failureCode": "card_declined",
    "failureMessage": "Your card was declined.",
    "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
  }
}

Manual recovery

The customer recovers an overdue subscription. The original charge reason is preserved.

Manual recovery

{
  "event": "payment.failed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "paymentContext": {
      "reason": "recurring_billing",
      "paymentLinkId": null,
      "recovery": {
        "type": "payment_recovery"
      }
    },
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043",
    "customerId": "user_123",
    "subscriptionId": "sub_1a2b3c4d",
    "provider": "stripe",
    "paymentMethod": "card",
    "subPaymentMethod": null,
    "failureCode": "card_declined",
    "failureMessage": "Your card was declined.",
    "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
  }
}

Dunning retries

The second automatic retry of a subscription resume charge, out of four allowed retries. The reason remains subscription_resume.

Dunning retries

{
  "event": "payment.failed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "paymentContext": {
      "reason": "subscription_resume",
      "paymentLinkId": null,
      "recovery": {
        "type": "dunning_retry",
        "attempt": 2,
        "maxAttempts": 4
      }
    },
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043",
    "customerId": "user_123",
    "subscriptionId": "sub_1a2b3c4d",
    "provider": "stripe",
    "paymentMethod": "card",
    "subPaymentMethod": null,
    "failureCode": "card_declined",
    "failureMessage": "Your card was declined.",
    "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
  }
}

No context

The charge context was not captured. Do not infer the original reason from the subscription’s current state.

No context

{
  "event": "payment.failed",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f",
  "mode": "live",
  "apiVersion": "2026-08-27",
  "data": {
    "paymentContext": null,
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043",
    "customerId": "user_123",
    "subscriptionId": "sub_1a2b3c4d",
    "provider": "stripe",
    "paymentMethod": "card",
    "subPaymentMethod": null,
    "failureCode": "card_declined",
    "failureMessage": "Your card was declined.",
    "recoveryUrl": "https://pay.commet.co/recover/tok_9f8e7d6c"
  }
}

Body

application/json

string

required

event

string

required

Allowed value: "payment.failed"

timestamp

string

required

organizationId

string

required

mode

enum<string>

required

Available options:

live,

sandbox

apiVersion

string

required

data

object

required

Show child attributes

Response

200

Return any 2xx status code to acknowledge receipt of the event.

Overview

Events

payment.failed

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`

Body

Response

​paymentContext

​reason

​paymentLinkId

​recovery

​recovery.attempt

​recovery.maxAttempts

Body

Response

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`