Troubleshooting

Match an add-on integration symptom to its cause and fix.

Each entry names the symptom, why it happens and the fix. All codes: Errors.

Registration and errors

Code	Cause	Fix
`paylexer_register_too_late`	`paylexer_register_platform()` ran outside `paylexer_init`	Register inside `add_action( 'paylexer_init', … )`, as shown in Register platform.
`paylexer_platform_name_required`	No `name` for the platform	Pass the platform you integrate as `name` (e.g. "Acme Bookings"), not your plugin's name.
`paylexer_duplicate_platform`	Another plugin already registered that platform ID	The merchant sees a notice naming both plugins; only one can integrate a platform.
`paylexer_not_connected`	PayLexer isn't connected on this site	The merchant connects the PayLexer plugin first (`paylexer_settings_url()`).
`paylexer_feature_not_declared`	The call needs a feature missing from `supports`	Add `refunds` or `subscriptions` when you register.
`paylexer_not_found`	The order or subscription isn't one your platform created	Each platform can reach only its own orders.

Start with PayLexer → Webhook logs. The PayLexer plugin logs each event there after verifying it and before firing your hooks.

Symptom	Cause	Fix
Hook never fires	The platform ID in the hook name differs from the registered one, or your plugin registered too late	Use `paylexer_platform_{id}_{event}` with the exact ID, and register inside `paylexer_init`. See Webhooks.
Order paid twice, or paid after a failure	A retry or out-of-order event	Be idempotent, lock per order, and never move a paid order back to unpaid. See Writing safe handlers.
Verified, but you don't fulfil	Matching on your own `reference`	`data.orderReference` is PayLexer's `ORD-…` reference. Save it on your order when you create the checkout.
Event answered `503`	No active plugin registered that platform	Activate your plugin; PayLexer retries a limited number of times.
Refund recorded twice	You handled your own refund again	Skip it when `$event->is_own_refund( 'your-id' )` (API 1.1 and later).

Symptom	Cause	Fix
No gateways returned	None enabled for this site or currency	Check PayLexer → Gateways, or drop the `currency` filter.
`paylexer_billing_address_required`	The gateway needs an address	Pass `customer.address`.
Subscription modal ends in `onPending`	Subscriptions can't be confirmed in the browser	Activate it from the `subscription_activated` webhook.
`paylexer_unknown_gateway`	Gateway not enabled for this site	Use a code from `paylexer_get_gateways()`.
`paylexer_currency_not_supported`	The gateway can't take this payment in that currency	Pick a gateway whose `currencies` includes it, or filter with `paylexer_get_gateways( array( 'currency' => … ) )`.
Checkout opens as a redirect, not a modal	PayLexer decides per gateway, from its own configuration	Nothing to set. `openCheckout()` follows `checkout.checkout` (`modal` or `redirect`). See Open checkout.

Was this page helpful?