payment_link.failed

{ "event": "payment_link.failed", "timestamp": "2026-06-23T14:30:00.000Z", "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f", "mode": "live", "apiVersion": "2026-08-27", "data": { "paymentContext": { "reason": "one_time_payment", "paymentLinkId": "pay_l1m2n3", "recovery": null }, "paymentId": "pay_l1m2n3", "status": "failed", "amount": 5000, "currency": "usd", "description": "One-time onboarding fee", "customerId": "user_123", "failureCode": "card_declined", "failureMessage": "Your card was declined.", "paymentMethod": "card", "subPaymentMethod": null } }

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.

Cuándo se dispara

Cuando se rechaza un intento de cobro sobre un link de pago. El link queda abierto — un link fallido se puede reintentar, y el cliente puede pagarlo de nuevo. Un intento exitoso posterior dispara payment_link.completed.

failureCode es el código del procesador (por ejemplo card_declined) y failureMessage es el motivo legible, o null cuando el proveedor no da ninguno.

El evento se dispara igual sin importar qué proveedor de pagos procese el cobro.

Cuerpo

application/json

string

requerido

event

string

requerido

Allowed value: "payment_link.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_link.failed

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`

Cuándo se dispara

Cuerpo

Respuesta

​paymentContext

​reason

​paymentLinkId

​recovery

​recovery.attempt

​recovery.maxAttempts

​Cuándo se dispara

Cuerpo

Respuesta

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`

Cuándo se dispara