3. Merchant Guide

Merchant Guide

How It Works

1. Customer reaches checkout and selects Bitcoin Lightning (CLINK) as payment method
2. The plugin creates a CLINK payment offer (noffer1... bech32 string) linked to the order
3. Customer scans/pastes the noffer string in a CLINK-compatible wallet
4. Wallet resolves the offer via Nostr relay and pays the Lightning invoice
5. The plugin's payment monitor receives confirmation via Nostr Kind 21001 events
6. Payment is marked as settled and the order advances

Adding CLINK as a Payment Method

1. Go to Admin > Settings > Payment Methods
2. Click Add Payment Method
3. Select Bitcoin Lightning (CLINK) (code: clink-lightning)
4. Configure the payment method args:
   • Relay URLs: Nostr relay(s) for payment communication
   • Offer Expiry Minutes: How long customers have to pay
5. Save

Order States

Payment State	Meaning
Created	CLINK offer generated, awaiting customer payment
Settled	Payment confirmed via Nostr relay or HTTP webhook
Error	Payment creation failed (e.g., SDK error)
Cancelled	Merchant or system cancelled the offer

Monitoring Payments

Via Admin API

query {
  clinkOffers(status: "pending", limit: 20) {
    totalItems
    items {
      id
      offerId
      noffer
      amountSats
      status
      bolt11Invoice
      expiresAt
      paidAt
    }
  }
}

Payment Flow

Order Created
    ↓
addPaymentToOrder(method: "clink-lightning")
    ↓
ClinkPaymentHandler.createPayment()
    ↓
ClinkOffer created in DB (status: "pending")
    ↓
noffer1... string returned to storefront
    ↓
[Customer pays via CLINK wallet]
    ↓
Nostr relay sends Kind 21001 event
    ↓
PaymentMonitorService decrypts & verifies
    ↓
ClinkOffer marked as "paid"
    ↓
Order advances to next state

Webhook Fallback

For wallets that don't support Nostr, the HTTP fallback endpoint accepts:

POST /payments/clink
Content-Type: application/json

{
  "offerId": "vendure_ORDERCODE_1234567890",
  "bolt11": "lnbc...",
  "preimage": "hex_preimage"
}

Response:

{ "success": true, "message": "Payment settled successfully" }