Listen for checkout payment errors from Paddle.js

What's new?

We added a new checkout.payment.error event for Paddle.js. 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, you can specify which payment methods to allow 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 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 enabled
• Display a custom message explaining the issue

Examples

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

1
2
3
4
5
6
7
1{
2  "name": "checkout.payment.error",
3  "type": "front-end_error",
4  "code": "no_payment_methods_available",
5  "detail": "No payment methods available",
6  "documentation_url": "https://developer.paddle.com/api-reference/overview"
7}

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.

Learn more