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 or 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	The Payment Intent expired, was already paid, or was cancelled. Check its status on your server first: if it succeeded, show the order as paid; otherwise create a fresh Payment Intent and a new Checkout instance.
`CHECKOUT_NETWORK_ERROR`	Yes	Keep the order unpaid and offer the customer another attempt.
`CHECKOUT_NO_PAYMENT_METHODS`	No	In live mode, connect and enable a payment method. Test mode always offers card payments.
`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. To see SDK diagnostics, reproduce the issue with a pk_test_… key: the SDK logs to the browser console in test mode and stays silent in live mode.

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.

Webhook deliveries

Dashboard → Webhooks lists every delivery with its event ID, attempt count, latest HTTP status, and last error.

Delivery status	Meaning
`delivered`	Your endpoint returned `2xx`.
`retrying`	Lynq will retry after a temporary failure.
`failed`	The delivery is non-retryable or the retry window ended.

Payment succeeded but the order is still unpaid

Find the Payment Intent in Dashboard → Payments, then inspect its webhook delivery. If delivery succeeded, search receiver logs by event ID and confirm the order comparison and database transaction. If delivery is retrying, restore the endpoint and let Lynq retry.

Delivery is retrying

Check the latest HTTP status or network error. 408, 429, 5xx, timeouts, and connection failures are temporary. Fix the receiver without changing the endpoint URL unless necessary.

Delivery failed immediately

Check for an unreachable destination and non-retryable 4xx responses. Confirm the URL is public HTTPS and the receiver is not rejecting valid signatures. Once it is fixed, open the delivery and choose Resend.

Signature verification started failing

Confirm the receiver uses the raw body and the current mode’s signing secret, and that it accepts any matching v1 signature. If the secret was rotated, the previous one stops signing when its overlap ends.

Exposed credentials

If a secret API key is exposed, roll it in API keys and choose Now, then install the new key in every server that uses it. Requests using the old key fail from that moment. If a webhook signing secret is exposed, rotate it with Now and install the new one in your receiver.

Contact support

Email support@lynq.am with:

Test or live mode
The Payment Intent ID, webhook event ID, or your order ID
The approximate time and your timezone
The error code, HTTP status, or delivery status, and the Lynq.js version

Never email secret API keys, client secrets, VPOS passwords, Idram secret keys, or webhook signing secrets.

Start here

Payment methods

Build your integration

Test and go live

Reference

Errors and troubleshooting

Thrown errors

`ConfigError`

`MountError`

`LynqErrorCode`

Customer-facing handling

Troubleshooting by symptom

Webhook deliveries

Exposed credentials

Contact support

​Thrown errors

​ConfigError

​MountError

​LynqErrorCode

​Customer-facing handling

​Troubleshooting by symptom

​Webhook deliveries

​Exposed credentials

​Contact support

Thrown errors

`ConfigError`

`MountError`

`LynqErrorCode`

Customer-facing handling

Troubleshooting by symptom

Webhook deliveries

Exposed credentials

Contact support