Errors and troubleshooting

Checkout has two error paths:

Synchronous integration errors are thrown while constructing or mounting Checkout.
Hosted Checkout initialization and loading errors are sent to onCheckoutError as LynqError.

Payment declines are not Checkout errors. They arrive through onPaymentResult with status: "requires_payment_method".

Thrown errors

`ConfigError`

Thrown when publicKey or clientSecret is missing, environment is invalid, or Checkout is constructed outside a browser. Check that client-only code creates the instance after hydration and that configuration is available at that time.

`MountError`

Thrown when:

The selector does not resolve to an element
This instance is already mounted
This instance was destroyed
Another Lynq Checkout is already mounted on the page

Fix the integration state before retrying; repeatedly calling mount() will not resolve these errors.

`LynqErrorCode`

Code	Retryable	Recommended handling
`CONFIG_ERROR`	No	Fix the constructor configuration or browser lifecycle.
`MOUNT_ERROR`	No	Fix the mount container or instance lifecycle.
`CHECKOUT_CONFIGURATION_ERROR`	No	Check the publishable key and client secret. Create a fresh Payment Intent if the session is invalid.
`CHECKOUT_SESSION_UNAVAILABLE`	No	Create a fresh Payment Intent and initialize a new Checkout instance.
`CHECKOUT_NETWORK_ERROR`	Yes	Keep the order unpaid and offer the customer another attempt.
`CHECKOUT_NO_PAYMENT_METHODS`	No	Configure and enable a method in the Payment Intent’s environment.
`CHECKOUT_UNAVAILABLE`	Yes	Show a temporary-unavailability message and offer retry.
`CHECKOUT_TIMEOUT`	Yes	Check network connectivity and offer a fresh attempt.

Use the runtime error.retryable value rather than maintaining your own retry table in application code.

Customer-facing handling

checkout.onCheckoutError((error) => {
  showAlert(error.message);

  if (error.retryable) {
    showRetryAction();
  } else {
    reportIntegrationIssue({ code: error.code });
  }
});

The message is display-safe. Log the code, SDK VERSION, Payment Intent ID, environment, and occurrence time for diagnostics. Do not log keys or client secrets.

Troubleshooting by symptom

Checkout never becomes ready

Handle onCheckoutError, confirm the container remains mounted, and check whether Content Security Policy or network controls block https://checkout.lynq.am. Use debug: true temporarily in a safe environment when diagnosing SDK initialization.

Checkout credentials are rejected

Create a fresh Payment Intent and confirm its environment matches the publishable key. Do not retrieve an old Payment Intent expecting to recover its client secret.

No payment methods are available

Check Dashboard → Payment methods in the Payment Intent’s environment. At least one configured method must be enabled.

The same page mounts Checkout twice

In component frameworks, ensure cleanup calls destroy() and development double-render behaviour does not leave the previous instance mounted.

The browser says success but the order is pending

This is expected until your server verifies the webhook. Inspect the delivery in Dashboard rather than fulfilling from the browser result.

If you cannot resolve the issue, contact support@lynq.am with redacted diagnostics.

Start here

Payment methods

Build your integration

Test and go live

Reference

Resources

Thrown errors

`ConfigError`

`MountError`

`LynqErrorCode`

Customer-facing handling

Troubleshooting by symptom

​Thrown errors

​ConfigError

​MountError

​LynqErrorCode

​Customer-facing handling

​Troubleshooting by symptom

Thrown errors

`ConfigError`

`MountError`

`LynqErrorCode`

Customer-facing handling

Troubleshooting by symptom