Skip to content

Guide for Merchants

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

Complete guide for merchants to set up Bitcoin Lightning payments via CLINK on their Medusa store.

Table of Contents

Overview

This plugin allows your Medusa store to accept Bitcoin Lightning payments using the CLINK protocol.

Key Benefits

  • ⚡ Instant payments - Lightning Network settles in seconds
  • 🔒 Self-custodial - Funds go directly to your Lightning node
  • 🌐 No web server required - Communication via Nostr relays
  • 💱 Auto conversion - Fiat to satoshis in real-time
  • 📱 QR codes - Customers scan and pay with any wallet

Requirements

For You (Merchant)

  1. A Lightning Node/Wallet that supports CLINK:

  2. Medusa v2.x store

  3. Node.js 18+

For Your Customers

Any CLINK-compatible wallet:

  • ShockWallet
  • ZEUS
  • Amethyst
  • Electrum with CLINK plugin

Installation

1. Install the Plugin

# In your Medusa project root
npm install medusa-plugin-bitcoin-lightning-via-clink

2. Configure medusa-config.ts

Add the payment provider to your Medusa config:

import { Modules } from "@medusajs/framework/utils"

module.exports = defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-plugin-bitcoin-lightning-via-clink",
            id: "clink",
            options: {
              // Required: Your CLINK offer string
              noffer: "noffer1...",
              
              // Currency conversion source
              currencySource: "coingecko",
              
              // Optional settings
              invoiceTimeout: 600,      // 10 minutes
              enableSubscriptions: false,
              refundContactEmail: "you@example.com",
              debug: false
            }
          }
        ]
      }
    }
  ]
})

3. Restart Medusa

npm run dev

Getting Your CLINK Offer

Your noffer1... string is like a Lightning address but works without a web server.

Option 1: ShockWallet (Mobile) - Recommended

  1. Download ShockWallet
  2. Create or import your Lightning wallet
  3. Go to Menu → Static Offer
  4. Copy the noffer1... string
  5. Paste into your Medusa config

Option 2: Lightning.Pub (Self-Hosted)

  1. Deploy Lightning.Pub
  2. Access your dashboard
  3. Navigate to Offers
  4. Copy the generated noffer1... string

Option 3: ZEUS Wallet

  1. Open ZEUS
  2. Go to Settings → CLINK
  3. Copy your noffer1... string

Configuration

Required Options

Option Type Description
noffer string Your CLINK offer string (starts with noffer1...)

Optional Options

Option Type Default Description
currencySource string coingecko Exchange rate source
fixedBtcRate number - Fixed BTC rate (when using fixed source)
invoiceTimeout number 600 Invoice expiry in seconds
pollInterval number 5000 Payment status check interval (ms)
maxPollAttempts number 120 Maximum polling attempts
enableSubscriptions boolean false Enable nDebit auto-renewal
refundContactEmail string - Email for refund requests
refundContactNostr string - Nostr pubkey for refunds
debug boolean false Enable debug logging

Enabling in Regions

  1. Go to Medusa Admin → Settings → Regions
  2. Edit your region
  3. Under Payment Providers, enable Lightning (CLINK)
  4. Save

Currency Sources

CoinGecko (Default)

  • Free, no API key required
  • Updates every 5 minutes
  • Supports 50+ currencies
currencySource: "coingecko"

Kraken

  • More accurate rates
  • API key optional (free tier available)
  • Updates every 5 minutes
currencySource: "kraken"

Fixed Rate

  • You set the BTC/fiat rate manually
  • Good for stable pricing
currencySource: "fixed",
fixedBtcRate: 65000  // 1 BTC = 65,000 USD

Manual

  • You enter prices directly in satoshis
  • No conversion needed
currencySource: "manual"

Subscription Setup

Enable auto-renewal for recurring payments.

1. Enable in Config

{
  enableSubscriptions: true
}

2. Customer Setup Flow

After first payment, customers can:

  1. Get their ndebit1... string from their wallet
  2. Paste it in the auto-renewal field
  3. Future payments process automatically

Supported Wallets for nDebit

Refund Process

Lightning refunds require manual processing.

Customer Refund Flow

  1. Customer contacts you via:

    • Email: you@example.com (if configured)
    • Nostr DM: npub1... (if configured)

  2. You process the refund manually:

    • Create a Lightning invoice from their wallet
    • Pay the invoice from your node

Setting Refund Contact

{
  refundContactEmail: "support@yourstore.com",
  refundContactNostr: "npub1..."
}

Troubleshooting

Payment Not Confirming

  1. Check if invoice has expired
  2. Verify Nostr relay connection
  3. Check logs: { debug: true }

Wrong Amount

  1. Verify currency source is working
  2. Check exchange rate cache
  3. Try a different currency source

Webhook Not Received

  1. Check webhook endpoint is accessible
  2. Verify webhook secret matches
  3. Check firewall rules

Enable Debug Logging

{
  debug: true
}

Getting Help

Clone this wiki locally