CLINK

Name: MedusaJS
Brand: Medusa

Accept Bitcoin Lightning payments via CLINK

medusa-plugin-bitcoin-lightning-via-clink

Bitcoin Lightning payment module for MedusaJS eCommerce via the CLINK protocol.

Features

⚡ Lightning Payments - Accept Bitcoin Lightning payments via CLINK protocol
🔒 Self-Custodial - Your node, your funds, no third-party
🌐 Nostr-Native - All communication via Nostr relays, no web server needed
💱 Auto Conversion - CoinGecko, Kraken, Fixed rate, or Manual
🔄 Subscriptions - Auto-renewal via CLINK Debits (nDebit)
📱 QR + Copy - Beautiful QR codes with one-click copy for invoices
🔐 Privacy - Ephemeral Nostr keys for payment requests
🛡️ Dual Confirmation - Webhook (primary) + Polling (backup)
📊 Admin Dashboard - Configure everything from the Medusa admin panel

What's in the Box

Component Description Copy to clipboardClinkPaymentProviderService Core payment provider with CLINK SDK integration Copy to clipboardCurrencyService Fiat-to-sats conversion (CoinGecko, Kraken, Fixed, Manual) Copy to clipboardSubscriptionService Recurring payments via nDebit protocol Admin Settings Widget Configure noffer, currency source, subscriptions, refunds Storefront Component QR code + copy + countdown timer + payment status polling Webhook Endpoint Real-time payment confirmations from CLINK relay Status Endpoint Backup polling for payment verification

Quick Start

1. Install

1
npm install medusa-plugin-bitcoin-lightning-via-clink

2. Configure

Add to your Copy to clipboard-config.ts:

1234567891011121314151617181920
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: {
              noffer: "noffer1...", // Your CLINK offer string
              currencySource: "coingecko",
              invoiceTimeout: 600,
              debug: false
            }
          }
        ]
      }

3. Enable in Admin

Go to Settings > Regions
Edit your region
Enable Lightning (CLINK) as a payment provider

4. Accept Payments!

Customers can now pay with Lightning at checkout.

Documentation

Full documentation lives on the GitHub Wiki:

How It Works

1234567891011121314151617181920
┌─────────────────────────────────────────────────────────────────┐
│                        CHECKOUT FLOW                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Customer selects "Pay with Lightning"                           │
│       │                                                          │
│       ▼                                                          │
│  Medusa requests invoice                                         │
│       │                                                          │
│       ▼                                                          │
│  CLINK SDK decodes nOffer → requests BOLT11 from your node       │
│       │                                                          │
│       ▼                                                          │
│  QR code + invoice displayed to customer                         │
│       │                                                          │
│       ▼                                                          │
│  Customer scans QR with Lightning wallet                         │
│       │                                                          │
│       ▼                                                          │
│  Payment confirmed via Webhook (primary) OR Polling (backup)     │

No web server needed for your Lightning node. All communication flows over Nostr. See the Wiki architecture page for the full data flow.

Requirements

Medusa v2.x
Node.js >= 18.0.0
A CLINK-compatible Lightning wallet/node:
- ShockWallet (iOS/Android/Desktop)
- Lightning.Pub (self-hosted)
- ZEUS (iOS/Android)
- Amethyst (Android)
- Electrum with CLINK plugin (Desktop)

Configuration Options

Option Type Required Default Description Copy to clipboardnoffer string Yes - Your CLINK offer string Copy to clipboardcurrencySource string No Copy to clipboardcoingecko Exchange rate source Copy to clipboardfixedBtcRate number No - Fixed BTC rate (if using Copy to clipboardfixed source) Copy to clipboardinvoiceTimeout number No Copy to clipboard600 Invoice expiry in seconds Copy to clipboardpollInterval number No Copy to clipboard5000 Polling interval in ms Copy to clipboardenableSubscriptions boolean No Copy to clipboardfalse Enable nDebit subscriptions Copy to clipboardmerchantPubkey string Only for subscriptions - Merchant Nostr pubkey (64-hex); required when Copy to clipboardenableSubscriptions Copy to clipboardwebhookSecret string No - HMAC secret to verify webhook payloads (see Security below) Copy to clipboardrefundContactEmail string No - Merchant email for refunds Copy to clipboardrefundContactNostr string No - Merchant Nostr for refunds Copy to clipboarddebug boolean No Copy to clipboardfalse Enable debug logging

Security

v1.0.2 hardened the plugin against common payment and network attacks:

BOLT11 validation - Invoices returned by your node are validated before being shown to customers: mainnet Copy to clipboardbc prefix, amount matches the requested total, and a reasonable expiry. Invalid invoices are rejected and the payment session is failed.
SSRF protection - Relay URLs are validated (Copy to clipboardwss:// only) and IP addresses are checked for safety. Localhost, Copy to clipboard.local domains, private/loopback/CGNAT/link-local IPs, and unsafe IPv6 ranges (ULA, link-local, multicast, IPv4-mapped) are rejected.
Webhook signature verification - Confirmations sent to the webhook endpoint are verified with an HMAC-SHA256 signature before the order is confirmed. Set a shared secret and the plugin will reject unsigned or tampered webhooks.
nDebit validation - Subscription debit pointers are decoded and validated (pubkey, relay) before use. A Copy to clipboardk1 correlation key ties each debit request to the originating subscription.
Payment hash correlation - The webhook verifies the payment's Copy to clipboardpayment_hash matches the expected session before confirming the order.

Webhook secret

Two ways to set it (env var takes precedence):

12
# Option 1: environment variable
CLINK_WEBHOOK_SECRET=your-secret npm start

1234
// Option 2: plugin option
options: {
  webhookSecret: "your-secret"
}

If no secret is configured, webhook signatures are not checked (single-tenant setups behind a firewall). Configure one in production. See the Configuration Wiki page for details.

See the Configuration Wiki page for details on each option.

Supported Wallets

For Merchants (to get your Copy to clipboardnOffer):

ShockWallet - Menu > Static Offer
Lightning.Pub - Dashboard > Offers
ZEUS - Settings > CLINK

For Customers (to pay):

Development

1234567891011
# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Watch mode
npm run dev

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

GPL-3.0 - See LICENSE for details.

Support

Other Conversations

In Medusa GH forum: https://github.com/medusajs/medusa/discussions/16162
In Medusa Discord: https://discord.com/channels/876835651130097704/1529853260276437123