Developer Documentation

Build payments into any app, anywhere in the Caribbean.

LuniPay gives Caribbean businesses a Stripe-class developer experience: prefixed API keys, signed webhooks, cursor-paginated REST, JavaScript and Python SDKs, and a hosted checkout that feels like the rest of your product.

If you have integrated Stripe before, this will feel familiar. You generate keys, create a checkout session, redirect your customer to a hosted page, and receive a signed webhook when they pay. The API surface is deliberately small — three concepts, not thirty.

// npm install lunipay
import LuniPay from 'lunipay';

const lunipay = new LuniPay(process.env.LUNIPAY_SECRET_KEY);

const session = await lunipay.checkout.sessions.create({
  amount: 5000,
  currency: 'usd',
  success_url: 'https://example.com/thanks',
});

console.log(session.url);

The three concepts

Almost everything you will build on LuniPay is a composition of three resources. Learn these and you have the API.

Checkout Session

A single payment in progress. Create one, redirect your customer, LuniPay hosts the payment page and fires a webhook when it completes.

Customer

Optional. Reuse billing details across invoices, recurring templates, and the customer portal.

Event

The immutable log of everything that has happened in your account. Every webhook delivery is a rendering of an event.

How a payment flows

A successful payment always follows the same path, no matter whether it comes from a checkout session, an invoice, or a payment link:

Your backend creates a resource with a secret key — a checkout_session, an invoice, or a payment_link.
You redirect or share the returned hosted URL with your customer.
Your customer pays on LuniPay-hosted infrastructure (3DS, receipts, and refunds all handled).
LuniPay writes a signed event to your account and POSTs it to every registered webhook endpoint.
Your backend verifies the signature and fulfills the order — ship the goods, flip the flag in your database, whatever.

Webhooks are the source of truth

Never mark an order as paid based on the URL redirect alone. The success URL is a UX cue. The signed webhook is the contract.

What to read next

Quick Start

Zero to a successful test payment in under 15 minutes.

Authentication

Generate keys, understand the sk_test / sk_live split, and learn what publishable keys unlock.

Accept a payment

The full guided tutorial — checkout session, redirect, webhook, order fulfillment.

Webhooks

Fan-out, signature verification, retries, and every supported event type.