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

```typescript
{
  resolve: "medusa-plugin-bitcoin-lightning-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

```typescript
{
  // 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:**
- [my.shockwallet.app/lapps](https://my.shockwallet.app/lapps)

### 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:
- ShockWallet: Settings → nDebit
- ZEUS: Settings → CLINK → nDebit
- Online: [my.shockwallet.app/lapps](https://my.shockwallet.app/lapps)

### 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

```typescript
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

- [Configuration](Configuration.md) - All options
- [Troubleshooting](Troubleshooting.md) - Common issues
- [Contributing](Contributing.md) - Help improve