Get started with the SDK

The lomi. SDK is the fastest way to call the lomi. API from your application code, create checkout sessions, manage customers and subscriptions, issue refunds, and verify webhooks, with typed methods and built-in error handling.

This guide uses the TypeScript SDK (@lomi./sdk). The same flow applies to Python, Go, and PHP.

Install the SDK

npm install @lomi./sdk

Also available with pnpm add, yarn add, or bun add. See the TypeScript SDK reference for other runtimes.

Add your test API key

Copy a test secret key (lomi_sk_test_…) from Settings → Access tokens and add it to a .env file. See Access tokens.

LOMI_SECRET_KEY=lomi_sk_test_xxxxxxxxxxxxxxxxxxxxxx

Let the CLI scaffold this for you

lomi init writes the SDK client, example files, and your .env automatically. See the CLI quickstart and Initialize a project.

Make your first sandbox call

Create first-call.ts, then fetch your sandbox balance to confirm the key works:

import { LomiSDK, LomiAuthError } from '@lomi./sdk';

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_SECRET_KEY!,
  environment: 'test', // sandbox; use 'live' only in production
});

async function main() {
  try {
    const balance = await lomi.accounts.getBalance();
    console.log('Balance:', balance);
  } catch (error) {
    if (error instanceof LomiAuthError) {
      console.error(`Auth failed [${error.statusCode}]: ${error.message}`);
      process.exit(1);
    }
    throw error;
  }
}

main();

npm install @lomi./sdk
# load .env with your tooling (dotenv, Next.js, etc.)
npx tsx first-call.ts

Create a test checkout

const session = await lomi.checkoutSessions.create({
  amount: 10000,
  currency_code: 'XOF',
  title: 'Premium subscription',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
});

console.log('Redirect to:', session.checkout_url);

Open checkout_url in your browser and pay with a sandbox test method.

Verify a webhook

Confirm events are authentic before trusting them, no hand-rolled HMAC required:

import { verifyWebhookSignature } from '@lomi./sdk';

const valid = verifyWebhookSignature(
  rawBody,                          // raw string or Buffer, not parsed JSON
  req.headers['x-lomi-signature'],
  process.env.LOMI_WEBHOOK_SECRET!,
);

if (!valid) return res.status(401).send('Invalid signature');

Forward events to your local server with the CLI, no ngrok required:

lomi listen http://localhost:3000/webhooks

See Listen for webhooks and Webhooks.

What to build next

Goal	Reference
Full TypeScript SDK API	TypeScript SDK
Other languages	Python · Go · PHP
Hosted checkout	Checkout
Recurring billing	Subscriptions
Error handling	Error handling

Two kinds of credentials

API key vs CLI token

The SDK uses your secret API key (LOMI_SECRET_KEY) in application code.

The CLI uses a separate CLI token from lomi login for terminal commands like checkout create and listen.

These are different credentials for different purposes.

Next steps

Make a test payment: CLI and cURL paths
Choose an integration: hosted checkout, links, subscriptions
Go live: production checklist

Get started with the SDK

On this page