Skip to content

payment.failed

payment.failed is sent by Neocarts when a subscription renewal charge did not go through: the provider refused the payment (status: "failed") or it stayed pending for more than a day and was marked expired (status: "expired"). Neocarts retries daily, up to five times per renewal order; every failed attempt is its own event with a growing attempt.

The fifth failure in a row pauses the subscription: alongside the payment.failed with next_attempt_at: null comes a subscription.paused with reason_key: "charge_failed".

Field Type Description
subscription_id string The subscription being charged.
attempt integer The number of this failed attempt within the current renewal, 1–5.
max_attempts integer Always 5.
next_attempt_at string, ISO 8601, nullable When Neocarts tries again — a day later. null on the fifth attempt: no more tries, the subscription is paused.

The rest of data is the payment snapshot.

The first failed renewal charge: the card was refused, the next attempt is a day away.

{
"id": "019a0b7c-1f3e-7c1a-9c6e-0b9b1c2d3e52",
"event": "payment.failed",
"created_at": "2026-11-01T09:00:14+00:00",
"shop_id": "7f3c2b1a-0d9e-4f8a-b7c6-d5e4f3a2b1c0",
"data": {
"id": "0199c0d1-2e3f-7a4b-8c5d-6e7f8a9b0c1d",
"order_id": "0199c0d0-1d2e-7f3a-8b4c-5d6e7f8a9b0c",
"provider": "plata-by-mono",
"status": "failed",
"amount": 231570,
"refunded_amount": 0,
"card_mask": "**** 4242",
"card_brand": "visa",
"created_at": "2026-11-01T09:00:12+00:00",
"subscription_id": "0199a1b3-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"attempt": 1,
"max_attempts": 5,
"next_attempt_at": "2026-11-02T09:00:14+00:00"
}
}

On the fifth attempt: "attempt": 5, "next_attempt_at": null, and at the same moment a subscription.paused.

  • Cancel nothing after the first failure: Neocarts will try again — the shopper receives an email too and can update the card.
  • If you warn the shopper yourself, take the date from next_attempt_at; when it is null, speak of a pause, not of a next attempt.
  • Do not count attempts yourself — rely on attempt and max_attempts: a redelivery with the same id carries the same values.
  • Handle the pause on subscription.paused, not on attempt: 5: the delivery order of the two events is not guaranteed.

Request headers, signature and retries are in the overview; the order of events is in the event flow.