Checkout events and errors

Events connect hosted Checkout to your surrounding page. Register handlers before mount() so you cannot miss readiness or initialization failures.

Recommended handlers

checkout
  .onReady(() => {
    hideCheckoutSkeleton();
  })
  .onValidation(({ canSubmit, fields }) => {
    updateSurroundingPageUi({ canSubmit, brand: fields.brand });
  })
  .onPaymentResult((result) => {
    if (result.status === "succeeded") {
      showSubmitted(result.paymentIntentId);
      return;
    }

    if (result.status === "processing") {
      showPending(result.paymentIntentId);
      return;
    }

    showPaymentError(result.error.message);
  })
  .onCheckoutError((error) => {
    showCheckoutError(error.message, { canRetry: error.retryable });
  });

Ready and validation

onReady means Checkout initialized and can accept customer input. Use it to remove loading UI; do not treat it as a payment event. onValidation reports the current hosted card-form state. It is useful when your surrounding page needs to react to whether Checkout can submit or to the detected card brand. Validation does not authorize or confirm payment.

Payment results

Result	Customer-facing UI	Server-side action
`succeeded`	Show that payment was submitted successfully.	Wait for and verify the success webhook before fulfilment.
`processing`	Show a pending state and tell the customer they do not need to resubmit.	Leave the order pending and wait for a webhook.
`requires_payment_method`	Display `result.error.message` and let the customer correct or replace the method.	Do not mark the order paid.

Authentication challenges and wallet redirects are handled internally and are not public result states. paymentMethod, when present, contains a non-sensitive summary. Card summaries can include brand, last four digits, expiry, and cardholder name; Idram summaries identify the wallet provider.

Checkout errors

onCheckoutError is for initialization and loading failures. It receives a LynqError with:

message: display-safe text you may show to the customer
code: stable value for programmatic handling and diagnostics
retryable: whether offering another attempt is reasonable

Payment declines are payment results, not Checkout errors.

Generic subscriptions

The named methods are the clearest choice for most integrations. The generic API is available for abstractions:

const handleReady = () => hideCheckoutSkeleton();

checkout.on("ready", handleReady);
checkout.off("ready", handleReady);

Pass the original handler reference to remove one listener. Call off(event) without a handler to remove every listener for that event. destroy() clears all listeners. See SDK reference for exact event payloads and Errors for handling each error code.

Start here

Payment methods

Build your integration

Test and go live

Reference

Resources

Recommended handlers

Ready and validation

Payment results

Checkout errors

Generic subscriptions

​Recommended handlers

​Ready and validation

​Payment results

​Checkout errors

​Generic subscriptions

Recommended handlers

Ready and validation

Payment results

Checkout errors

Generic subscriptions