Skip to content

Subscriptions

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

Complete guide to auto-renewal subscriptions using CLINK Debits.

Overview

Enable automatic recurring payments with CLINK Debits (nDebit). Customers authorize future payments once, and renewals process automatically.

Features

  • 🔄 Automatic renewals - No manual intervention
  • ⚡ Instant processing - Lightning speed
  • 🔒 Secure authorization - Cryptographic signatures
  • ❌ Revocable - Customers can cancel anytime

How It Works

First Payment (Manual)

Customer → Selects CLINK → 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 in Config

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

2. Create Subscription Products

In Medusa Admin:

  1. Products → Add Product
  2. Set product type to "Subscription"
  3. Configure billing interval

3. Optional Settings

{
  // Days before expiry to remind customer
  renewalReminderDays: 3,
  
  // Grace period for failed payments (days)
  gracePeriodDays: 7
}

Customer Setup

Step 1: First Payment

Customer pays normally via QR code.

Step 2: Get nDebit String

ShockWallet:

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

ZEUS:

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

Online:

Step 3: Enable Auto-Renewal

After first payment, on order confirmation page:

┌─────────────────────────────────────────────┐
│  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

Customer can verify in My Account → Subscriptions:

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

Technical Details

nDebit Authorization

When customer provides ndebit1...:

  1. Decode - Extract pubkey, relay, permissions
  2. Encrypt - Store securely in database
  3. Use - Send CLINK Debit request on renewal

Payment Flow

1. Subscription due date arrives
2. Plugin creates CLINK Debit request (kind 21002)
3. Request sent to customer's wallet via Nostr
4. Wallet auto-authorizes payment
5. Invoice paid automatically
6. Subscription renewed

Security

  • nDebit encrypted at rest
  • Cryptographic signature required
  • Amount must match subscription
  • Customer can revoke anytime

Managing Subscriptions

Customer Actions

View Subscription:

  1. My Account → Subscriptions
  2. See status, next renewal, payment history

Disable Auto-Renewal:

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

Update nDebit:

  1. My Account → Subscriptions
  2. Click "Update Payment Method"
  3. Paste new ndebit1...

Merchant Actions

View Subscriptions:

  1. Admin → Orders → Subscriptions
  2. Filter by status

Manual Renewal:

  1. Select subscription
  2. Click "Renew Now"
  3. Customer pays via QR code

Cancel Subscription:

  1. Select subscription
  2. Click "Cancel"
  3. Confirm

Troubleshooting

Auto-Renewal Not Working

  1. Check nDebit validity

    • Must start with ndebit1
    • From compatible wallet

  2. Check wallet connectivity

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

  3. Check payment limits

    • Sufficient balance
    • Channel capacity adequate

Customer Can't Find nDebit

Guide to:

Renewal Fails

  1. Enable debug mode
  2. Check logs for errors
  3. Verify Nostr relay connection
  4. Customer may need to re-authorize

FAQ

Can I change my nDebit?

Yes! Update anytime from My Account → Subscriptions.

What if wallet runs out of funds?

Renewal fails. Customer gets notification to top up.

Can I pay manually instead?

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

Is nDebit secure?

Yes! Cryptographically signed and encrypted. Only usable for authorized subscription.

Multiple subscriptions?

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

API Reference

nDebit Data Model

interface NDebitData {
  id: string
  customer_id: string
  subscription_id: string
  ndebit_string: string  // Encrypted
  pubkey: string
  relay: string
  created_at: Date
  updated_at: Date
}

Events

  • subscription.renewal_attempted - Renewal initiated
  • subscription.renewal_succeeded - Payment confirmed
  • subscription.renewal_failed - Payment failed
  • subscription.cancelled - Subscription cancelled

Next Steps

Clone this wiki locally