Skip to content

Guide for Subscriptions

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

Complete guide for setting up auto-renewal subscriptions using CLINK Debits (nDebit).

Table of Contents

Overview

CLINK Debits (nDebit) enable automatic recurring payments without QR code scanning. Once set up, future subscription payments process automatically.

Benefits

  • 🔄 Automatic - No manual intervention needed
  • ⚡ Instant - Payments process immediately
  • 🔒 Secure - Cryptographically authorized
  • ❌ Revocable - Customers can cancel anytime

How It Works

First Payment (Manual):
  Customer → Scans QR → Pays → Order Confirmed

Setup Auto-Renewal:
  Customer → Gets nDebit → Pastes in Settings → Auto-Renewal Enabled

Future Payments (Automatic):
  Subscription Due → Plugin sends nDebit request → Wallet auto-pays → Renewal Complete

Merchant Setup

1. Enable Subscriptions

Add to your medusa-config.ts:

{
  resolve: "medusa-bitcoin-lightning-payment-module-via-clink",
  id: "clink",
  options: {
    noffer: "noffer1...",
    enableSubscriptions: true,  // Enable this!
    // ... other options
  }
}

2. Create Subscription Products

In Medusa Admin:

  1. Create a product
  2. Set as "Subscription" type
  3. Configure billing interval (monthly, yearly, etc.)

3. Optional: Set Renewal Window

Configure when renewal reminders are sent:

{
  // Days before expiry to remind customer
  renewalReminderDays: 3
}

Customer Setup

Step 1: First Payment

Customer pays normally via QR code scan.

Step 2: Get nDebit String

After first payment, customer needs their ndebit1... string.

From ShockWallet:

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

From ZEUS:

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

Step 3: Enable Auto-Renewal

  1. After first payment, on the order confirmation page
  2. Look for "Setup Auto-Renewal" section
  3. Paste ndebit1... string
  4. Click "Enable Auto-Renewal"
┌─────────────────────────────────────────────┐
│  Setup Auto-Renewal for Future Payments     │
│                                             │
│  Your subscription will renew automatically │
│  using Lightning payments.                  │
│                                             │
│  1. Open your Lightning wallet              │
│  2. Get your nDebit string                  │
│  3. Paste it below:                         │
│                                             │
│  [ndebit1qvqsyqjqxuurvwpcxc6rvv...]        │
│                                             │
│  [Enable Auto-Renewal]                      │
│                                             │
└─────────────────────────────────────────────┘

Step 4: Verify Setup

Customer can verify in My Account → Subscriptions:

  • Status: "Auto-Renewal Active"
  • Next renewal date shown
  • Option to disable

Technical Details

nDebit Authorization

When a customer provides their ndebit1... string:

  1. Plugin decodes the string to get:

    • Nostr public key
    • Relay URL
    • Permission scope

  2. Stored securely (encrypted at rest)

  3. On renewal date:

    • Plugin sends CLINK Debit request (kind 21002)
    • Customer's wallet auto-authorizes payment
    • Invoice is paid automatically

Security

  • nDebit strings are encrypted in storage
  • Each payment requires cryptographic signature
  • Customers can revoke authorization anytime
  • No pre-shared secrets required

Payment Limits

  • Amount must match subscription price
  • Cannot exceed wallet balance
  • Cannot exceed channel capacity

Troubleshooting

Auto-Renewal Not Working

  1. Check nDebit is valid

    • Ensure ndebit1... string is complete
    • Verify it's from a compatible wallet

  2. Check wallet connectivity

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

  3. Check payment limits

    • Sufficient wallet balance
    • Channel capacity adequate

Customer Can't Find nDebit

Guide them to:

Renewal Fails

  1. Check logs with debug: true
  2. Verify Nostr relay connection
  3. Customer may need to re-authorize

Disable Auto-Renewal

Customer can:

  1. Go to My Account → Subscriptions
  2. Click "Disable Auto-Renewal"
  3. Confirm action

FAQ

Can I change my nDebit?

Yes! You can update it anytime from My Account → Subscriptions.

What if my wallet runs out of funds?

The renewal will fail. You'll receive a notification to top up.

Can I pay manually instead?

Yes! Disable auto-renewal and pay via QR code each time.

Is my nDebit secure?

Yes! It's cryptographically signed and encrypted. The merchant can only use it for your authorized subscription.

Can I have multiple subscriptions?

Yes! Each subscription can have its own nDebit or share one.

Getting Help

Clone this wiki locally