Skip to content

Configuration

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

Complete reference for all plugin configuration options.

Basic Configuration

// medusa-config.ts
{
  resolve: "bitcoin-lightning-payment-module-for-medusajs-via-clink",
  id: "clink",
  options: {
    noffer: "noffer1...",  // Required
    // ... other options
  }
}

Required Options

noffer

Type: string

Your CLINK offer string. This is how the plugin communicates with your Lightning node.

How to get it:

  • ShockWallet: Receive → CLINK Offer
  • Lightning.Pub: Dashboard → Offers
  • ZEUS: Settings → CLINK

Format: noffer1qvqsyq...

Currency Options

currencySource

Type: "coingecko" | "kraken" | "fixed" | "manual"

Default: "coingecko"

Exchange rate source for fiat-to-satoshi conversion.

Source API Key Required Rate Limit Notes
coingecko No 10-50/min Most popular, free
kraken Optional 15/min More accurate
fixed No None You set the rate
manual No None Enter sats directly

Example:

currencySource: "kraken"

fixedBtcRate

Type: number

Fixed BTC/fiat rate. Only used when currencySource: "fixed".

Example:

currencySource: "fixed",
fixedBtcRate: 65000  // 1 BTC = 65,000 USD

Payment Options

invoiceTimeout

Type: number

Default: 600 (10 minutes)

Invoice expiry time in seconds. After this time, the invoice is no longer valid.

Valid range: 60 - 86400 (1 minute to 24 hours)

Example:

invoiceTimeout: 300  // 5 minutes

pollInterval

Type: number

Default: 5000 (5 seconds)

How often to check for payment confirmation (in milliseconds).

Example:

pollInterval: 3000  // Check every 3 seconds

maxPollAttempts

Type: number

Default: 120

Maximum number of times to poll for payment confirmation.

With default settings: 120 attempts × 5 seconds = 10 minutes (matches invoiceTimeout)

Example:

maxPollAttempts: 60  // Stop after 60 attempts

Subscription Options

enableSubscriptions

Type: boolean

Default: false

Enable auto-renewal subscriptions via CLINK Debits (nDebit).

Example:

enableSubscriptions: true

Refund Options

refundContactEmail

Type: string

Email address for refund requests. Displayed to customers after payment.

Example:

refundContactEmail: "support@yourstore.com"

refundContactNostr

Type: string

Nostr pubkey for refund requests. Displayed to customers after payment.

Example:

refundContactNostr: "npub1..."

Debug Options

debug

Type: boolean

Default: false

Enable detailed logging for troubleshooting.

Example:

debug: true

Logs include:

  • Payment initiation
  • Currency conversion
  • Webhook events
  • Errors

Complete Example

{
  resolve: "bitcoin-lightning-payment-module-for-medusajs-via-clink",
  id: "clink",
  options: {
    // Required
    noffer: "noffer1qvqsyqjqxuurvwpcxc6rvvrxxsurqep5vfjk2wf4v33nsenrxumnyvesxfnrswfkvycrwdp3x93xydf5xg6rzce4vv6xgdfh8quxgct9x5erxvspremhxue69uhhgetnwskhyetvv9ujumrfva58gmnfdenjuur4vgqzpccxc30wpf78wf2q78wg3vq008fd8ygtl4qy06gstpye3h5unc47xmee6z",
    
    // Currency
    currencySource: "coingecko",
    
    // Payment
    invoiceTimeout: 600,
    pollInterval: 5000,
    maxPollAttempts: 120,
    
    // Subscriptions
    enableSubscriptions: true,
    
    // Refunds
    refundContactEmail: "support@mystore.com",
    refundContactNostr: "npub1...",
    
    // Debug
    debug: false
  }
}

Environment Variables

You can use environment variables for sensitive configuration:

{
  noffer: process.env.CLINK_NOFFER,
  refundContactEmail: process.env.CONTACT_EMAIL,
  debug: process.env.NODE_ENV === "development"
}

Validation

The plugin validates configuration on startup:

  • noffer must start with noffer1
  • invoiceTimeout must be between 60 and 86400
  • fixedBtcRate is required when using fixed source

Invalid configuration will throw an error at startup.

Next Steps

Clone this wiki locally