Skip to content

Troubleshooting

Jump to bottom
WoompaLoompa edited this page Jul 21, 2026 · 3 revisions

Common issues and solutions for the CLINK payment plugin.

Table of Contents

Payment Issues

Payment Not Confirming

Symptoms:

  • Customer pays but order remains pending
  • QR code shows but payment never confirms

Solutions:

  1. Check invoice expiration

    • Default timeout is 10 minutes
    • Increase invoiceTimeout if needed

  2. Verify Nostr relay connection

    • Check if the relay URL in your noffer is accessible
    • Try a different relay

  3. Enable debug mode

    { debug: true }

    Check logs for errors

  4. Check webhook endpoint

    • Ensure /clink/webhook is accessible
    • Verify firewall rules

Wrong Amount

Symptoms:

  • Invoice shows incorrect satoshi amount
  • Amount doesn't match fiat price

Solutions:

  1. Check currency source

    { debug: true }

    Look for conversion logs

  2. Verify exchange rate

    • CoinGecko/Kraken may be down
    • Try fixed source temporarily

  3. Check currency code

    • Must be ISO 4217 (USD, EUR, GBP)
    • Case-sensitive

QR Code Not Displaying

Symptoms:

  • Empty checkout page
  • No QR code shown

Solutions:

  1. Check browser console

    • Look for JavaScript errors
    • Verify script loading

  2. Clear cache

    • Browser cache
    • Medusa cache

  3. Verify plugin installation

    npm ls medusa-bitcoin-lightning-payment-module-via-clink

Configuration Issues

Invalid noffer String

Error: Invalid CLINK offer string format

Solutions:

  1. Verify format

    • Must start with noffer1
    • Only lowercase letters and numbers
    • No spaces or special characters

  2. Re-copy from wallet

    • ShockWallet: Receive → CLINK Offer
    • Ensure complete string

  3. Check for typos

    • Compare with original
    • Use a text editor to verify

Plugin Not Found

Error: Cannot find module 'medusa-bitcoin-lightning-payment-module-via-clink'

Solutions:

  1. Verify installation

    npm install medusa-bitcoin-lightning-payment-module-via-clink

  2. Check node_modules

    ls node_modules | grep medusa-bitcoin

  3. Reinstall

    rm -rf node_modules
npm install

Provider Not Showing in Admin

Solutions:

  1. Verify config syntax

    • Check for commas, brackets
    • Ensure valid TypeScript

  2. Restart Medusa

    npm run dev

  3. Check medusa-config.ts location

    • Must be in project root

Currency Issues

Exchange Rate Errors

Error: CoinGecko API error or Kraken API error

Solutions:

  1. Check network

    curl https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd

  2. Use fixed rate temporarily

    {
  currencySource: "fixed",
  fixedBtcRate: 65000
}

  3. Check API limits

    • CoinGecko: 10-50 requests/minute
    • Kraken: 15 requests/minute

Cache Not Working

Symptoms:

  • Rates change frequently
  • Too many API calls

Solutions:

  1. Verify cache TTL

    • Default: 5 minutes
    • Check getCacheStatus()

  2. Clear and reload

    • Restart Medusa
    • Cache rebuilds automatically

Subscription Issues

nDebit Not Working

Symptoms:

  • Auto-renewal fails
  • Payment not processed

Solutions:

  1. Verify nDebit format

    • Must start with ndebit1
    • From compatible wallet

  2. Check wallet online

    • Customer's wallet must be reachable
    • Relay must be accessible

  3. Verify authorization

    • Amount must match subscription
    • Cannot exceed limits

Customer Can't Find nDebit

Guide them to:

ShockWallet:

  1. Open ShockWallet
  2. Settings → nDebit
  3. Copy ndebit1... string

ZEUS:

  1. Open ZEUS
  2. Settings → CLINK → nDebit
  3. Copy ndebit1... string

Online:

Debug Mode

Enable detailed logging:

{
  debug: true
}

Log Output

[ClinkPayment] Initiating payment
[ClinkPayment] Currency source: coingecko
[ClinkCurrency] Fetching CoinGecko rate for usd
[ClinkCurrency] Converted 10 USD = 15114 sats (rate: 66165)
[ClinkPayment] Payment initiated: 15114 sats, expires at 1234567890
[ClinkWebhook] Received webhook event
[ClinkWebhook] Payment confirmed for session clink_1234567890_abc123

Common Debug Messages

Message Meaning
Initiating payment Customer selected CLINK
Converted X USD = Y sats Currency conversion successful
Payment initiated Invoice created
Received webhook event Payment confirmation received
Payment confirmed Order will be completed

Getting More Help

If these solutions don't help:

  1. Enable debug mode

  2. Collect logs

  3. Open an issue

    • GitHub Issues
    • Include: Medusa version, plugin version, logs, steps to reproduce

  4. Check existing issues

    • Your problem may already be solved

Related Pages

Clone this wiki locally