@moneydevkit/nextjs

moneydevkit checkout library for embedding Lightning-powered payments inside Next.js (App Router) apps.

Setup

Create a Money Dev Kit account at moneydevkit.com or run npx @moneydevkit/create to generate credentials locally, then grab your api_key, webhook_key, and mnemonic.
Install the SDK in your project:
```
npm install @moneydevkit/nextjs
```

Add required secrets to .env (or similar):

MDK_ACCESS_TOKEN=your_api_key_here
MDK_MNEMONIC=your_mnemonic_here

Quick Start (Next.js App Router)

1. Trigger a checkout from any client component

// app/page.js
'use client'

import { useCheckout } from '@moneydevkit/nextjs'
import { useState } from 'react'

export default function HomePage() {
  const { createCheckout, isLoading } = useCheckout()
  const [error, setError] = useState(null)

  const handlePurchase = async () => {
    setError(null)

    const result = await createCheckout({
      type: 'AMOUNT',      // or 'PRODUCTS' for product-based checkouts
      title: 'Describe the purchase shown to the buyer',
      description: 'A description of the purchase',
      amount: 500,         // 500 USD cents or Bitcoin sats
      currency: 'USD',     // or 'SAT'
      successUrl: '/checkout/success',
      metadata: {
        customField: 'internal reference for this checkout',
        name: 'John Doe'
      }
    })

    if (result.error) {
      setError(result.error.message)
      return
    }

    window.location.href = result.data.checkoutUrl
  }

  return (
    <div>
      {error && <p style={{ color: 'red' }}>{error}</p>}
      <button onClick={handlePurchase} disabled={isLoading}>
        {isLoading ? 'Creating checkout…' : 'Buy Now'}
      </button>
    </div>
  )
}

2. Render the hosted checkout page

// app/checkout/[id]/page.js
"use client";
import { Checkout } from "@moneydevkit/nextjs";
import { use } from "react";

export default function CheckoutPage({ params }) {
  const { id } = use(params);

  return <Checkout id={id} />;
}

3. Expose the unified Money Dev Kit endpoint

// app/api/mdk/route.js
export { POST } from "@moneydevkit/nextjs/server/route";

4. Configure Next.js

// next.config.js / next.config.mjs
import withMdkCheckout from '@moneydevkit/nextjs/next-plugin'

export default withMdkCheckout({})

You now have a complete Lightning checkout loop: the button creates a session, the dynamic route renders it, and the webhook endpoint signals your Lightning node to claim paid invoices.

Customer Data

Collect and store customer information with each checkout. Pass customer to pre-fill data and requireCustomerData to prompt the user for specific fields:

const result = await createCheckout({
  type: 'AMOUNT',
  title: "Premium Plan",
  description: 'Monthly subscription',
  amount: 1000,
  currency: 'USD',
  successUrl: '/checkout/success',
  // Pre-fill customer data (optional)
  customer: {
    name: 'John Doe',
    email: 'john@example.com',
  },
  // Require fields at checkout (shows form if not provided)
  requireCustomerData: ['name', 'email', 'company'],
})

How it works

If all requireCustomerData fields are already provided in customer, the form is skipped
If some required fields are missing, a form is shown to collect only those fields
Email is required to create a customer record. Without email, customer data is attached to the checkout but no customer record is created
Field names are flexible: tax_id, tax-id, taxId, or Tax ID all normalize to taxId
Custom fields (beyond name, email, externalId) are stored in customer metadata

Returning customers

Customers are matched by email or externalId. When a match is found:

Existing customer data is preserved and not overwritten
Only missing fields from requireCustomerData are requested
All checkouts and orders are linked to the same customer record

Using externalId for authenticated users

When your user is already authenticated in your app, pass externalId to link checkouts to their account:

const result = await createCheckout({
  type: 'AMOUNT',
  title: "Premium Plan",
  description: 'Monthly subscription',
  amount: 1000,
  currency: 'USD',
  successUrl: '/checkout/success',
  customer: {
    externalId: user.id,  // Your app's user ID
    name: user.name,
    email: user.email,
  },
  requireCustomerData: ['name', 'email'],
})

When externalId is provided:

The system assumes the user is authenticated
If the customer already exists (matched by externalId), their stored name and email are used
Only fields missing from the customer record are requested
This prevents authenticated users from being asked for data you already have

Product Checkouts

Sell products defined in your Money Dev Kit dashboard using type: 'PRODUCTS':

import { useCheckout, useProducts } from '@moneydevkit/nextjs'

function ProductPage() {
  const { createCheckout, isLoading } = useCheckout()
  const { products } = useProducts()

  const handleBuyProduct = async (productId) => {
    const result = await createCheckout({
      type: 'PRODUCTS',
      product: productId,
      successUrl: '/checkout/success',
    })

    if (result.error) return
    window.location.href = result.data.checkoutUrl
  }

  return (
    <div>
      {products?.map(product => (
        <button key={product.id} onClick={() => handleBuyProduct(product.id)}>
          Buy {product.name} - ${(product.price?.priceAmount ?? 0) / 100}
        </button>
      ))}
    </div>
  )
}

Checkout Types

type: 'AMOUNT' - For donations, tips, or custom amounts. Requires amount field.
type: 'PRODUCTS' - For selling products. Requires product field with a product ID. Amount is calculated from product price.

Note: Product prices are returned in base currency units:

USD: cents (divide by 100 for dollars)

SAT: satoshis (no conversion needed)

Pay What You Want (CUSTOM prices)

Products can have CUSTOM prices that let customers choose their own amount. When a checkout includes a product with a CUSTOM price, the checkout UI automatically shows an amount input field:

// Create a checkout for a product with CUSTOM pricing
const result = await createCheckout({
  type: 'PRODUCTS',
  product: customPriceProductId,  // Product configured with CUSTOM price in dashboard
  successUrl: '/checkout/success',
})

The customer enters their desired amount during checkout. For USD, amounts are in dollars (converted to cents internally). For SAT, amounts are in satoshis.

Verify successful payments

When a checkout completes, use useCheckoutSuccess() on the success page

'use client'

import { useCheckoutSuccess } from '@moneydevkit/nextjs'

export default function SuccessPage() {
  const { isCheckoutPaidLoading, isCheckoutPaid, metadata } = useCheckoutSuccess()

  if (isCheckoutPaidLoading || isCheckoutPaid === null) {
    return <p>Verifying payment…</p>
  }

  if (!isCheckoutPaid) {
    return <p>Payment has not been confirmed.</p>
  }

  // We set 'name' when calling navigate(), and it's accessible here on the success page.
  console.log('Customer name:', metadata?.name) // "John Doe"

  return (
    <div>
      <p>Payment confirmed. Enjoy your purchase!</p>
    </div>
  )
}

L402: Pay-per-call API Endpoints

Gate any API route behind a Lightning payment using the L402 protocol (HTTP 402). No accounts, no subscriptions — clients pay a Lightning invoice and get immediate access.

How it works

Client                          Your Server                    Lightning
  │                                │                              │
  │  GET /api/premium              │                              │
  │──────────────────────────────► │                              │
  │                                │                              │
  │  402 Payment Required          │                              │
  │  { invoice, macaroon, amount } │                              │
  │ ◄────────────────────────────  │                              │
  │                                │                              │
  │  pay invoice ──────────────────┼────────────────────────────► │
  │  ◄── preimage ─────────────────┼──────────────────────────────│
  │                                │                              │
  │  GET /api/premium              │                              │
  │  Authorization: L402 <macaroon>:<preimage>                     │
  │──────────────────────────────► │                              │
  │                                │  verify credential + preimage│
  │  200 OK { data }               │                              │
  │ ◄────────────────────────────  │                              │

Client requests a protected endpoint without credentials
Server returns 402 with a Lightning invoice and a signed credential
Client pays the invoice and receives a preimage (proof of payment)
Client retries with Authorization: L402 <macaroon>:<preimage>
Server verifies the credential, expiry, and preimage — then forwards to the handler

Setup

Make sure MDK_ACCESS_TOKEN is set in your environment (same key used for checkout):

MDK_ACCESS_TOKEN=your_api_key_here
MDK_MNEMONIC=your_mnemonic_here

Basic usage

// app/api/premium/route.ts
import { withPayment } from '@moneydevkit/nextjs/server'

const handler = async (req: Request) => {
  return Response.json({ content: 'Premium data' })
}

export const GET = withPayment(
  { amount: 100, currency: 'SAT' },
  handler,
)

Every GET /api/premium request without valid credentials returns a 402 with a Lightning invoice. After payment, the same request with the authorization header returns the premium data.

Dynamic pricing

Pass a function instead of a fixed number to compute the price from the request:

// app/api/ai/route.ts
import { withPayment } from '@moneydevkit/nextjs/server'

const handler = async (req: Request) => {
  const { model } = await req.json()
  const result = await runInference(model)
  return Response.json({ result })
}

export const POST = withPayment(
  {
    amount: (req: Request) => {
      const url = new URL(req.url)
      const tier = url.searchParams.get('tier')
      if (tier === 'pro') return 500
      return 100
    },
    currency: 'SAT',
  },
  handler,
)

The pricing function is evaluated both when creating the invoice and when verifying the credential. If the price changes between issuance and verification (e.g., the client replays a cheap credential on an expensive tier), the request is rejected with amount_mismatch.

Fiat pricing

Use currency: 'USD' to price in US cents. The SDK converts to sats at the current exchange rate when generating the invoice:

export const GET = withPayment(
  { amount: 50, currency: 'USD' },  // $0.50
  handler,
)

Credential expiry

Credentials (and their invoices) expire after 15 minutes by default. Override with expirySeconds:

export const GET = withPayment(
  { amount: 100, currency: 'SAT', expirySeconds: 300 },  // 5 minutes
  handler,
)

Client integration

Any HTTP client can consume an L402 endpoint:

# 1. Request the protected resource
curl -s https://example.com/api/premium

# Response: 402
# {
#   "macaroon": "eyJ...",
#   "invoice": "lnbc...",
#   "paymentHash": "abc123...",
#   "amountSats": 100,
#   "expiresAt": 1234567890
# }

# 2. Pay the invoice with any Lightning wallet and get the preimage

# 3. Retry with the credential and preimage
curl -s https://example.com/api/premium \
  -H "Authorization: L402 eyJ...:ff00aa..."

# Response: 200 { "content": "Premium data" }

The WWW-Authenticate header follows the bLIP-26 format:

WWW-Authenticate: L402 macaroon="eyJ...", invoice="lnbc..."

Programmatic client (Node.js / agent)

async function callPaidEndpoint(url: string, payFn: (invoice: string) => Promise<string>) {
  // Step 1: get the 402 challenge
  const challenge = await fetch(url)
  if (challenge.status !== 402) return challenge

  // The credential is in the `macaroon` field (L402 naming convention)
  const { macaroon: credential, invoice } = await challenge.json()

  // Step 2: pay the invoice (returns preimage)
  const preimage = await payFn(invoice)

  // Step 3: retry with credential + proof of payment
  return fetch(url, {
    headers: { Authorization: `L402 ${credential}:${preimage}` },
  })
}

Deferred settlement

By default, withPayment marks the credential as used immediately before your handler runs. If your handler fails after the credential is consumed, the payer can't retry.

Use withDeferredSettlement when the service delivery might fail and you want the payer to be able to retry. Your handler receives a settle() callback - call it only after you've successfully delivered the service:

// app/api/ai/route.ts
import { withDeferredSettlement, type SettleResult } from '@moneydevkit/nextjs/server'

const handler = async (req: Request, settle: () => Promise<SettleResult>) => {
  const { prompt } = await req.json()

  // Do the expensive work first
  const result = await runAiInference(prompt)

  // Work succeeded - now mark the credential as used
  const { settled } = await settle()
  if (!settled) {
    return Response.json({ error: 'settlement_failed' }, { status: 500 })
  }

  return Response.json({ result })
}

export const POST = withDeferredSettlement(
  { amount: 100, currency: 'SAT' },
  handler,
)

If your handler returns without calling settle() (e.g. it throws or the service fails), the credential stays valid and the payer can retry with the same macaroon and preimage.

settle() is callable only once per request. A second call returns { settled: false, error: 'already_settled' } without hitting the backend.

Error codes

Status	Code	Meaning
402	`payment_required`	No credentials provided - pay the returned invoice
401	`invalid_credential`	Credential is malformed, has a bad signature, or the L402 header is garbled
401	`invalid_payment_proof`	Preimage does not match the payment hash
401	`credential_consumed`	Credential has already been used
403	`resource_mismatch`	Credential was issued for a different endpoint
403	`amount_mismatch`	Credential was issued for a different price
500	`configuration_error`	`MDK_ACCESS_TOKEN` is not set
500	`pricing_error`	Dynamic pricing function threw an error
502	`checkout_creation_failed`	Failed to create the checkout or invoice

Note: A 402 is only returned when no L402/LSAT authorization header is present. If the header is present but malformed or invalid, you get a 401 - not a new invoice.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

@moneydevkit/nextjs

Setup

Quick Start (Next.js App Router)

1. Trigger a checkout from any client component

2. Render the hosted checkout page

3. Expose the unified Money Dev Kit endpoint

4. Configure Next.js

Customer Data

How it works

Returning customers

Using externalId for authenticated users

Product Checkouts

Checkout Types

Pay What You Want (CUSTOM prices)

Verify successful payments

L402: Pay-per-call API Endpoints

How it works

Setup

Basic usage

Dynamic pricing

Fiat pricing

Credential expiry

Client integration

Programmatic client (Node.js / agent)

Deferred settlement

Error codes

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

@moneydevkit/nextjs

Setup

Quick Start (Next.js App Router)

1. Trigger a checkout from any client component

2. Render the hosted checkout page

3. Expose the unified Money Dev Kit endpoint

4. Configure Next.js

Customer Data

How it works

Returning customers

Using externalId for authenticated users

Product Checkouts

Checkout Types

Pay What You Want (CUSTOM prices)

Verify successful payments

L402: Pay-per-call API Endpoints

How it works

Setup

Basic usage

Dynamic pricing

Fiat pricing

Credential expiry

Client integration

Programmatic client (Node.js / agent)

Deferred settlement

Error codes