> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Listen for checkout payment errors from Paddle.js

Detect when no valid payment methods are available for a customer, so you can implement fallback flows.

---

## What's new?

We added a new [`checkout.payment.error` event](https://developer.paddle.com/paddlejs/payment/checkout-payment-error.md) for [Paddle.js](https://developer.paddle.com/paddlejs/overview.md). It's emitted when a customer can't use any of the allowed payment methods, giving you a reliable signal to recover the checkout flow.

## How it works

When [opening a checkout](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md), you can [specify which payment methods to allow](https://developer.paddle.com/build/checkout/set-up-checkout-default-settings.md) using the `allowedPaymentMethods` setting. This lets you control which payment options are available to your customers at checkout.

However, there are cases where the payment methods you've allowed aren't available to a particular customer. For example, if you open a checkout that only allows Apple Pay, but the customer's device or browser doesn't support Apple Pay, the checkout errors.

Previously, there was no reliable way to detect this programmatically. Now, you can listen for the [`checkout.payment.error` event](https://developer.paddle.com/paddlejs/payment/checkout-payment-error.md) emitted by Paddle.js.

This is useful when you want to optimize for a specific payment method but need a graceful fallback when it's not available, helping you avoid stranding customers on an errored checkout. You could:

* Reopen the checkout with alternative [payment methods](https://developer.paddle.com/concepts/payment-methods/overview.md) enabled
* Display a custom message explaining the issue

## Examples

This example callback event is emitted when no valid payment methods are available.

```json
{
  "name": "checkout.payment.error",
  "type": "front-end_error",
  "code": "no_payment_methods_available",
  "detail": "No payment methods available",
  "documentation_url": "https://developer.paddle.com/api-reference/overview"
}
```

## Next steps

This change is live in Paddle.js now, so you can start listening for `checkout.payment.error` when you're ready.

You don't need to do anything to get the latest version of Paddle.js — we serve the latest version automatically.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `checkout.payment.error` | Paddle.js event | added | Paddle.js | Emitted when a payment fails during checkout. |