Common issues and solutions for the CLINK payment plugin.

## Table of Contents

- [Payment Issues](#payment-issues)
- [Configuration Issues](#configuration-issues)
- [Currency Issues](#currency-issues)
- [Subscription Issues](#subscription-issues)
- [Debug Mode](#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**
   ```typescript
   { 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**
   ```typescript
   { 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**
   ```bash
   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**
   ```bash
   npm install medusa-plugin-bitcoin-lightning-via-clink
   ```

2. **Check node_modules**
   ```bash
   ls node_modules | grep medusa-bitcoin
   ```

3. **Reinstall**
   ```bash
   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**
   ```bash
   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**
   ```bash
   curl https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd
   ```

2. **Use fixed rate temporarily**
   ```typescript
   {
     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](https://my.shockwallet.app/lapps)

---

## Debug Mode

Enable detailed logging:

```typescript
{
  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](Configuration.md)
- [Currency Sources](Currency-Sources.md)
- [Subscriptions](Subscriptions.md)