lomi.
Fundamentals

Getting started

Set up your lomi. integration and start accepting payments in minutes.

Getting started

Get your lomi. integration running in minutes. Whether you're a startup launching your MVP or an established business, we've streamlined the onboarding process to get you accepting payments very fast.

Business tiers

lomi. offers two verification paths to accommodate businesses at different stages:

Starter

Perfect for startups, indie hackers, and MVPs testing the market.

  • Requirements: Valid government-issued ID (passport, national ID, or driver's license).
  • Transaction limit: 650,000 F CFA (~$1,000 USD).
  • Approval time: Less than an hour.

Start as a 'Starter' venture to validate your product, then upgrade to 'Business' when you're ready to scale.

Business

For established businesses ready for unlimited transaction processing.

  • Requirements: Business registration, and proof of address.
  • Transaction limit: Unlimited.
  • Approval time: 24 hours.

Quick start

Create your account

Sign up at dashboard.lomi.africa and complete the onboarding flow:

  1. Create an account via email or use your Google, Github, LinkedIn or Microsoft account to sign in.
  2. Provide your personal details (name, phone, country, address, use-case)
  3. Upload an ID document (for Starter) or full business documents.

We request an ID document to verify your identity and becasue we need to know who you are to enable you to accept payments. This is a mandatory step for all users, this information can be communicated to other of our partners, including PSPs, banks and regulators. For more information, please refer to our Privacy Policy. We will never sell your data to third parties or use it for any other purpose than to provide you with our services.

Once submitted, Starter accounts are approved instantly. Business accounts are reviewed within 24 hours.

Get your access tokens

Navigate to Settings → Access tokens in your dashboard to find your unique keys.

lomi. provides two types of keys for each environment:

Key typePrefixUsage
Publishable keypk_test_... / pk_live_...Client-side safe. Limited operations.
Secret keysk_test_... / sk_live_...Server-side only. Full API access.

Never expose secret keys in client-side code. Use publishable keys for frontend web applications and mobile applications.

Install the SDK

Choose your language and install the lomi. SDK:

# Using npm
npm install @lomi./sdk

# Using pnpm

pnpm add @lomi./sdk

# Using yarn

yarn add @lomi./sdk
pip install lomi-sdk
go get github.com/lomiafrica/lomi-go-sdk

Add to your composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/lomiafrica/lomi./"
    }
  ],
  "require": {
    "lomi/lomi-sdk": "dev-main#apps/sdks/php"
  }
}

Then run:

composer install
# Using npm
npm install @lomi./sdk-next

# Using pnpm

pnpm add @lomi./sdk-next

Set your environment variables

Configure your API credentials:

export LOMI_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxx
export LOMI_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxxxxxxxx

Make your first API call

Initialize the SDK and verify your connection:

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

// Initialize the SDK
const lomi = new LomiSDK({
  apiKey: process.env.LOMI_SECRET_KEY!,
  environment: 'live', // Use 'live' for production
});

async function listCustomers() {
  try {
    const customers = await lomi.customers.list();
    console.log('Customers:', customers);
  } catch (error) {
    console.error('Error:', error);
  }
}

listCustomers();
import os
from lomi import LomiClient, LomiError

# Initialize the SDK
client = LomiClient(
    api_key=os.environ["LOMI_SECRET_KEY"],
    environment="live"
)

try:
    customers = client.customers.list()
    print("Customers:", customers)
except LomiError as e:
    print(f"Error: {e}")
package main

import (
    "context"
    "fmt"
    "os"
    
    lomi "github.com/lomiafrica/lomi-go-sdk"
)

func main() {
configuration := lomi.NewConfiguration()
client := lomi.NewAPIClient(configuration)

    auth := context.WithValue(
        context.Background(),
        lomi.ContextAPIKeys,
        map[string]lomi.APIKey{
            "ApiKeyAuth": {Key: os.Getenv("LOMI_SECRET_KEY")},
        },
    )

    customers, _, err := client.CustomersAPI.ListCustomers(auth).Execute()
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Customers: %v\n", customers)

}
<?php
require_once 'vendor/autoload.php';

use Lomi\Configuration;
use Lomi\Api\CustomersApi;

$config = Configuration::getDefaultConfiguration()
    ->setApiKey('X-API-KEY', getenv('LOMI_SECRET_KEY'));

$apiInstance = new CustomersApi(null, $config);

try {
    $customers = $apiInstance->listCustomers();
    print_r($customers);
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}
// lib/lomi/server.ts (Server-side)
import { LomiSDK } from '@lomi./sdk';

export const lomi = new LomiSDK({
  apiKey: process.env.LOMI_SECRET_KEY!,
  environment: 'live',
});

// app/customers/page.tsx (Server Component)
import { lomi } from '@/lib/lomi/server';

export default async function CustomersPage() {
  const customers = await lomi.customers.list();
  
  return (
    <ul>
      {customers.data?.map((customer) => (
        <li key={customer.id}>{customer.name}</li>
      ))}
    </ul>
  );
}

Using curl:

curl -X GET "https://sandbox.api.lomi.africa/customers" \
  -H "X-API-KEY: ${LOMI_SECRET_KEY}"

Create a checkout session

Create a hosted checkout page to accept payments:

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

const lomi = new LomiSDK({
apiKey: process.env.LOMI_SECRET_KEY!,
environment: 'live',
});

async function createCheckout() {
  const session = await lomi.checkoutSessions.create({
    amount: 5000, // 5,000 F CFA
    currency_code: 'XOF',
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel',
    customer_email: 'customer@example.com',
    title: 'Premium Coffee Mug',
  });

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

createCheckout();
import os
from lomi import LomiClient

client = LomiClient(
    api_key=os.environ["LOMI_SECRET_KEY"],
    environment="live"
)

session = client.checkout_sessions.create({
    "amount": 5000,  # 5,000 F CFA
    "currency_code": "XOF",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "customer_email": "customer@example.com",
    "title": "Premium Coffee Mug"
})

print(f"Redirect customer to: {session['checkout_url']}")
sessionData := lomi.CheckoutSessionsCreate{
    Amount:        lomi.PtrInt32(5000),
    CurrencyCode:  lomi.PtrString("XOF"),
    SuccessUrl:    lomi.PtrString("https://yoursite.com/success"),
    CancelUrl:     lomi.PtrString("https://yoursite.com/cancel"),
    CustomerEmail: lomi.PtrString("customer@example.com"),
    Title:         lomi.PtrString("Premium Coffee Mug"),
}

session, \_, err := client.CheckoutSessionsAPI.CreateCheckoutSession(auth).
CheckoutSessionsCreate(sessionData).
Execute()

if err != nil {
fmt.Printf("Error: %v\n", err)
return
}

fmt.Printf("Redirect customer to: %s\n", \*session.CheckoutUrl)
use Lomi\Api\CheckoutSessionsApi;
use Lomi\Model\CheckoutSessionsCreate;

$checkoutApi = new CheckoutSessionsApi(null, $config);

$session = $checkoutApi->createCheckoutSession(
    new CheckoutSessionsCreate([
        'amount' => 5000, // 5,000 F CFA
        'currency_code' => 'XOF',
        'success_url' => 'https://yoursite.com/success',
        'cancel_url' => 'https://yoursite.com/cancel',
        'customer_email' => 'customer@example.com',
        'title' => 'Premium Coffee Mug'
    ])
);

header('Location: ' . $session->getCheckoutUrl());
exit;

Set up webhooks

Webhooks notify your server about events like successful payments:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json({
verify: (req: any, \_res, buf) => {
req.rawBody = buf;
},
}));

app.post('/webhook', (req: any, res) => {
const signature = req.headers['x-lomi-signature'] as string;
const secret = process.env.LOMI_WEBHOOK_SECRET!;

// Verify signature
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(req.rawBody)
.digest('hex');

if (signature !== expectedSignature) {
return res.status(400).send('Invalid signature');
}

const event = req.body;

switch (event.type) {
case 'PAYMENT_SUCCEEDED':
console.log('Payment succeeded:', event.data);
// Fulfill the order
break;

}

res.status(200).json({ received: true });
});

app.listen(3000);
import hmac
import hashlib
import os
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('x-lomi-signature')
    secret = os.environ['LOMI_WEBHOOK_SECRET'].encode()

    expected = hmac.new(secret, request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({'error': 'Invalid signature'}), 400

    event = request.json

    if event['type'] == 'PAYMENT_SUCCEEDED':
        print('Payment succeeded:', event['data'])
        # Fulfill the order

    return jsonify({'received': True})

if __name__ == '__main__':
    app.run(port=3000)
func webhookHandler(w http.ResponseWriter, r *http.Request) {
    signature := r.Header.Get("x-lomi-signature")
    secret := os.Getenv("LOMI_WEBHOOK_SECRET")
    
    body, _ := io.ReadAll(r.Body)
    
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    
    if !hmac.Equal([]byte(signature), []byte(expected)) {
        http.Error(w, "Invalid signature", http.StatusBadRequest)
        return
    }
    
    var event map[string]interface{}
    json.Unmarshal(body, &event)
    
    if event["type"] == "PAYMENT_SUCCEEDED" {
        log.Printf("Payment succeeded: %v", event["data"])
        // Fulfill the order
    }
    
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]bool{"received": true})
}
<?php
$signature = $_SERVER['HTTP_X_LOMI_SIGNATURE'] ?? '';
$secret = getenv('LOMI_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
http_response_code(400);
exit('Invalid signature');
}

$event = json_decode($payload, true);

if ($event['type'] === 'PAYMENT_SUCCEEDED') {
    error_log('Payment succeeded: ' . json_encode($event['data']));
// Fulfill the order
}

http_response_code(200);
echo json_encode(['received' => true]);

Remember to:

  • Set your LOMI_WEBHOOK_SECRET environment variable
  • Use ngrok to expose your local server during development
  • Register your webhook URL in the dashboard under Webhooks to get your webhook secret and get notified when a payment is successful.

Next steps

Support

Fundamentals

Fundamental concepts and setup for a successful integration.

Environment variables

Securely manage your API keys and environment variables.

On this page

Getting started
Business tiers
Starter
Business
Quick start
Create your account
Get your access tokens
Install the SDK
Set your environment variables
Make your first API call
Create a checkout session
Set up webhooks
Next steps
Support