Troubleshooting

Common issues and solutions for the CLINK payment plugin.

Table of Contents

• Payment Issues
• Configuration Issues
• Currency Issues
• Subscription Issues
• Debug Mode

---

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-plugin-bitcoin-lightning-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-plugin-bitcoin-lightning-via-clink'

Solutions:

1. Verify installation

   npm install medusa-plugin-bitcoin-lightning-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:

• my.shockwallet.app/lapps

---

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

• Configuration
• Currency Sources
• Subscriptions