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

El motivo original del cobro y cómo se inició este intento. La recuperación nunca reemplaza el motivo original. El contexto puede ser null si no se capturó, incluso en reintentos de facturas históricas.

Campos y motivos de pago

`reason`

stringEl motivo original, que se conserva entre intentos de pago.

`paymentLinkId`

string | nullEl ID público del enlace de pago, o null si el cobro no se originó en uno. Es independiente del motivo y de la forma de recuperación.

`recovery`

object | nullEs null cuando el cobro no recupera una suscripción. payment_recovery identifica la recuperación manual de una suscripción vencida, la vuelta después de una cancelación por impago o el reintento de una reanudación fallida. Reintentar el checkout inicial o un pago único no es recuperación. dunning_retry identifica un reintento automático de cobro, no de entrega del webhook.

`recovery.attempt`

integerLa posición del reintento de cobro en el calendario de dunning, empezando en 1. El rechazo original no es un reintento. Sólo aparece en dunning_retry.

`recovery.maxAttempts`

integerEl total de reintentos automáticos aplicable al cobro cuando empezó el intento. No representa los reintentos restantes. Sólo aparece en dunning_retry.

reason	Cuándo se usa
`first_subscription_payment`	El pago inicial de una suscripción.
`trial_conversion`	El pago al finalizar un período de prueba gratuito.
`recurring_billing`	Una renovación de la suscripción.
`plan_change`	Un cobro por un cambio de plan.
`reactivation`	Un cobro para reactivar una suscripción cancelada.
`subscription_resume`	Un cobro para reanudar una suscripción pausada.
`one_time_payment`	Un pago único, incluidos los enlaces de pago.
`overage`	Un cobro por consumo que supera lo incluido en el plan.
`adjustment`	Un cobro de una factura de ajuste.

Primer intento

El intento original de cobro, antes de la recuperación.

Primer intento

{
  "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"
  }
}

Recuperación manual

El cliente recupera una suscripción con un pago vencido. El motivo original del cobro se conserva.

Recuperación manual

{
  "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"
  }
}

Reintentos de dunning

El segundo reintento automático de un cobro por reanudación, de cuatro permitidos. El motivo sigue siendo subscription_resume.

Reintentos de dunning

{
  "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"
  }
}

Sin contexto

No se capturó el contexto del cobro. No deduzcas el motivo original a partir del estado actual de la suscripción.

Sin contexto

{
  "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"
  }
}

Cuerpo

application/json

string

requerido

event

string

requerido

Allowed value: "payment.failed"

timestamp

string

requerido

organizationId

string

requerido

mode

enum<string>

requerido

Opciones disponibles:

live,

sandbox

apiVersion

string

requerido

data

object

requerido

Show child attributes

Respuesta

200

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

Introducción

Eventos

payment.failed

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`

Cuerpo

Respuesta

​paymentContext

​reason

​paymentLinkId

​recovery

​recovery.attempt

​recovery.maxAttempts

Cuerpo

Respuesta

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`