Skip to content

Troubleshooting

Jump to bottom
D edited this page Jul 31, 2026 · 2 revisions

Troubleshooting

Checkout stays on "Processing your payment…"

The form's loading spinner only clears when the client module reaches the invoice stage. Work through:

  1. Hard-refresh / clear cache — the modules are ES modules served per-request; a stale cached copy can silently fail.
  2. Module scripts must load. OC4 injects the payment form with $('#checkout-confirm').load(...), and jQuery 3.7 strips <script type="module"> tags from injected HTML. The current template works around this by creating the module <script> elements from an inline classic script. If you see raw <script type="module" src=...> tags in your rendered form instead of the loader IIFE, your install is running an old template — reinstall.
  3. Check asset MIME types. Both .js and .mjs must be served as text/javascript. If your server serves .mjs as application/octet-stream, module imports fail: 
    curl -sI http://YOUR-STORE/extension/clink/catalog/view/javascript/clink/lib/clink-nostr.mjs
    Fix Apache/Nginx MIME config as needed.
  4. Check the browser console. A red SyntaxError/MIME type/Failed to fetch module error points at the module chain. console.error('[CLINK] Payment init failed:', ...) shows the server-side error surfaced by getInvoiceData or requestInvoice.
  5. Is the merchant node online? The relay must accept kind-21001 events and the merchant must respond. From a browser terminal: 
    node --experimental-websocket e2e.mjs   # see repository / wiki repo test scripts
  6. Verify getInvoiceData returns JSON for the order: 
    http://YOUR-STORE/index.php?route=extension/clink/payment/clink.getInvoiceData&order_id=<id>

"Invoice amount mismatch" / bolt11 never recorded

parseBolt11Amount converts bolt11 units to sats. Correct table: p→÷10000, n→÷10, u→×100, m→×100000. Earlier builds (≤1.0.0) used the wrong multipliers and rejected valid invoices. Upgrade to 1.0.1+ and re-test.

Live BTC rate ignored — always the 65000 fallback

If getInvoiceData always returns rate: 65000 (the hardcoded fallback) and the log repeats No rate available for USD, using fallback 65000, two bugs in ≤1.0.1 kept the CoinGecko fetch from ever running:

  1. Cache miss short-circuit — OpenCart's file cache returns [] (empty array), not false, on a miss. The old check if ($cached !== false) return (float) $cached; treated [] as a cached 0, which is <= 0 and fell back without ever calling CoinGecko. Fixed to truthy check.
  2. HTTP 403 from CoinGecko — the PHP stream request sent no User-Agent, and CoinGecko rejects such requests. The request now sends User-Agent: OpenCart-CLINK/1.0.1.

Upgrade to 1.0.2+. If you still see the fallback, clear system/storage/cache/cache.clink_rate_*.json and confirm outbound HTTPS to api.coingecko.com is allowed. A live rate returns something like {"rate": 63695, "amount_sats": 204098} for a $130 order.

Payments list is empty after installing the zip

The OC4 installer copies zip entries verbatim into extension/<code>/, and the Payments list scans extension/*/admin/controller/payment/*.php. If the zip has an upload/ prefix (OC3 layout) nothing is found. Use the OC4-native clink.ocmod.zip (entries at the zip root). See Installation.

"Path clink/ already exists!"

Leftover state from a previous broken install. Clean extension/clink/, the stale row in oc_extension_install (or oc_extension), and any leftover app-path copies, then reinstall.

Relay responses are ignored

Some relays (e.g. strfry) send ["EVENT", <subscription_id>, <event>] — three elements. The client uses data[2] (object) with a data[1] fallback. If your client logs responses that never match, check it reads the third element.

Orders created but status never updates to paid

The merchant node must call the webhook (extension/clink/payment/clink.webhook) with bolt11 + preimage. Confirm the node is configured with the store's webhook URL and, if set, the webhook secret. See Configuration.

Debugging tools

  • OpenCart error log: system/storage/logs/error.log — CLINK logs rate fallback and bolt11 mismatches here
  • Test scripts: /tmp/clink_e2e/ (relay client simulation: run.mjs, diag.mjs, probe.mjs)
  • Browser console is the fastest way to see the exact client error

Clone this wiki locally