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

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.

When this fires

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.

Body

application/json

string

required

event

string

required

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

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`

When this fires

Body

Response

​paymentContext

​reason

​paymentLinkId

​recovery

​recovery.attempt

​recovery.maxAttempts

​When this fires

Body

Response

paymentContext

`reason`

`paymentLinkId`

`recovery`

`recovery.attempt`

`recovery.maxAttempts`

When this fires