payment.failed

A payment was not taken: a card declined on the checkout, the shopper back from a gateway unpaid, or an upsell declined. The cart is kept. Once per order at a gateway.

CODE

next.on('payment.failed', (data, event) => {});

Data

Present: always; optional when it may be missing; campaign once the campaign is loaded; priced once the server priced the cart.

Field	Type	Present
`method`	`string`	always	The API's code: `card_token`, `paypal`, `apple_pay`, `google_pay`, `klarna`, …
`ref_id`	`string`	optional	The order the payment was for; none for a card declined before an order was created.
`error`	`Failure`	always	`declined` (`decline_code` from the gateway) or `payment_failed` (back from a gateway).

Failure

Why something failed: the same shape on sdk.error and on every *.failed event.

Field	Type	Present
`code`	`"network"` \| `"timeout"` \| `"server"` \| `"rejected"` \| `"declined"` \| `"payment_failed"` \| `"auth"` \| `"too_many_requests"` \| `"unavailable"`	always	`network` (no answer), `timeout`, `server` (5xx), `rejected` (4xx), `declined` (the card or the gateway), `payment_failed` (the gateway sent the shopper back unpaid), `auth` (401, 403), `too_many_requests` (429), or `unavailable` (storage blocked or full).
`message`	`string`	optional	For developers and logs, never for shoppers.
`status`	`number`	optional	The HTTP status, when the API answered.
`decline_code`	`string`	optional	The store's `payment_response_code` for a decline (`3005`). The shopper's sentence for it is `payment.errors.<code>` in the address service's texts: Payment errors.

Example

The second argument, with data inside. See Events for the envelope's fields.

CODE

{
  "event_id": "3f2b8c1d9e7a4b6c8d5e2f1a0b9c8d7e",
  "event_type": "payment.failed",
  "object": "payment",
  "data": {
    "method": "card_token",
    "error": {
      "code": "declined",
      "status": 400,
      "message": "Insufficient funds",
      "decline_code": "51"
    }
  },
  "created_at": "2026-11-04T08:30:00.000Z",
  "session_id": "0b8f3c2d1e4a4f6b9c7d5e3f2a1b0c9d",
  "sdk_version": "0.5.0"
}