Action guide
Know exactly which charge failed, when and why
POST
/v1/events · invoice.payment_failedEmit an `invoice.payment_failed` event whenever a charge attempt fails, at initial capture, on retry, or after the card was updated.
When to emit
Inside the webhook handler for `invoice.payment_failed` or `charge.failed`, scoped to the customer organization.
Example payload
await recalled.events.create({
action: "invoice.payment_failed",
actor: { id: user.id, email: user.email },
organization: user.organizationId,
metadata: {
amount: "value",
currency: "value",
reason: "value"
},
});Metadata to include
Keep metadata flat and consistent across your service so it plays well with search and CSV exports.
| Key | Purpose |
|---|---|
amount | Amount that failed, in smallest unit |
currency | ISO 4217 code |
reason | card_declined, insufficient_funds, expired_card, do_not_honor |
providerEventId | Stripe evt_xxx or equivalent |
Suggested retention
Keep for at least 18 months to handle disputes and dunning investigations.