> ## Documentation Index
> Fetch the complete documentation index at: https://commet.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# payment.failed
> Se dispara cuando falla un cobro de suscripción, incluidos cobros de reanudación e intentos de recuperación
## 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.
### `reason`
`string`
El motivo original, que se conserva entre intentos de pago.
### `paymentLinkId`
`string | null`
El 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 | null`
Es 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`
`integer`
La 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`
`integer`
El 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. |
El intento original de cobro, antes de la recuperación.
```json 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"
}
}
```
El cliente recupera una suscripción con un pago vencido. El motivo original del cobro se conserva.
```json 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"
}
}
```
El segundo reintento automático de un cobro por reanudación, de cuatro permitidos. El motivo sigue siendo subscription\_resume.
```json 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"
}
}
```
No se capturó el contexto del cobro. No deduzcas el motivo original a partir del estado actual de la suscripción.
```json 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"
}
}
```
## OpenAPI
````yaml /openapi/es/webhooks/2026-08-27.json webhook payment.failed
openapi: 3.1.0
info:
title: Commet Webhooks
version: '2026-08-27'
description: >-
Outbound webhook events emitted by the Commet API. Each event is delivered
as a signed POST to your configured endpoints.
servers: []
security: []
paths: {}
````
## Related topics
- [payment_failed](/docs/es/api-reference/errors/payment_failed.md)
- [Manejar pagos fallidos](/docs/es/handle-failed-payments.md)
- [payment.recovered](/docs/es/webhooks/payment-recovered.md)
- [subscription.past_due](/docs/es/webhooks/subscription-past-due.md)
- [Create webhook endpoint](/docs/es/api-reference/webhooks/create-webhook-endpoint.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.