LuniPay Docs

Guides

Next.js ecommerce example

Clone a small storefront that creates LuniPay checkout sessions, redirects customers to hosted checkout, and confirms orders from webhook events.

The example app is the fastest way to see a real LuniPay sandbox integration end-to-end. It uses Next.js App Router, TypeScript, Tailwind, a cookie-backed cart, a server-side checkout route, and a webhook endpoint.

View the GitHub repo

Clone the source and inspect the checkout and webhook handlers.

Open the live demo

Try the hosted storefront before running it locally.

What this example covers

Use it as a reference for creating checkout sessions with a secret key, redirecting to the returned hosted URL, keeping publishable and secret keys separate, and receiving signed webhook events.

Run it locally

git clone https://github.com/Lunipay/nextjs-ecommerce-example.git
cd nextjs-ecommerce-example
pnpm install
cp .env.local.example .env.local
# Fill in LUNIPAY_SECRET_KEY and NEXT_PUBLIC_LUNIPAY_PUBLISHABLE_KEY
pnpm dev

Then open http://localhost:3000. Use a test-mode key pair from Settings -> Developerso all sessions, payments, and webhook events stay in the sandbox.

Environment variables

VariableRequiredPurpose
LUNIPAY_SECRET_KEYYesSandbox secret key, prefixed sk_test_. Keep this server-side only.
NEXT_PUBLIC_LUNIPAY_PUBLISHABLE_KEYYesSandbox publishable key, prefixed pk_test_. Safe to expose in the browser.
LUNIPAY_WEBHOOK_SECRETProductionWebhook signing secret used to verify LuniPay-Signature.
LUNIPAY_API_URLNoAPI base override. Defaults to https://www.lunipay.io/api/v1.
NEXT_PUBLIC_APP_URLNoPublic app URL used to build success and cancel redirect URLs.

Use the www API host

The example uses https://www.lunipay.io/api/v1 directly. Do not point API clients at the apex host, because redirects can strip the Authorization header in common HTTP clients.

Payment flow

  1. The customer adds products to a cart.
  2. The app calls POST /api/checkout on its own backend.
  3. The backend creates a LuniPay checkout session with amount, currency, line items, and redirect URLs.
  4. The browser receives the hosted checkout URL and redirects the customer to LuniPay.
  5. After payment, LuniPay redirects the customer to the success page and sends a signed webhook event to the app.

Files to read first

  • src/lib/lunipay.ts - the single HTTP client wrapper for the LuniPay API.
  • src/app/api/checkout/route.ts - creates the checkout session on the server.
  • src/app/api/webhooks/lunipay/route.ts - receives webhook events and verifies signatures.
  • src/app/success/page.tsx - customer return page after hosted checkout.

Next steps