A payment link charge attempt failed.
All webhook payloads follow a consistent top-level structure with event-specific data nested within the data object.
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.
The payment link ID.
The link status. Always "failed" for this event.
The amount that was attempted in cents (100 = $1.00).
The payment currency code.
The payment description shown to the customer.
The customer ID, or null when the link is not tied to a customer. Returns your externalId if you provided one when creating the customer, otherwise returns the Commet publicId.
The failure code from the payment processor.
A human-readable failure message.
The payment method: card, oxxo, or mercado_pago. Null when unknown.
The source of funds for this charge, when reported by the provider. Null when unavailable or unknown.
{
"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
}
}When a charge attempt on a payment link is declined. The link stays open — a failed link is retryable, and the customer can pay it again. A later successful attempt fires payment_link.completed.
failureCode is the processor's code (for example card_declined) and failureMessage is the human-readable reason, or null when the provider gives none.
The event fires the same way regardless of which payment provider processes the charge.
How is this guide?