lomi. Payment Elements

lomi. Payment Elements allow you to accept card payments directly within your application without redirecting users to a hosted checkout page. This gives you full control over the user experience while lomi. handles the payment processing complexity.

lomi. Payment Elements are powered by secure, PCI-compliant infrastructure. You never touch raw card data.

Overview

There are three ways to integrate lomi. Payments:

Method	Use Case
TypeScript SDK (`@lomi./sdk`)	Apps web (Vanilla JS, React, Vue, etc.) pour Payment Elements
React Native SDK (`@lomi/react-native`)	Native mobile apps for iOS and Android
Embedded Checkout (`@lomi./embed`)	iframe-based integration preserving lomi.'s full UI

Installation

bash npm install @lomi./sdk

bash npm install @lomi/react-native

bash npm install @lomi./embed

Quick start

Get Your API Keys

You'll need two keys from your lomi. Dashboard:

Publishable Key (lomi_pk_...): Used client-side to initialize the SDK
Secret Key (lomi_sk_...): Used server-side to create Payment Intents

Never expose your Secret Key in client-side code!

Create a Payment Intent (Server-Side)

Before collecting payment, create a Payment Intent on your server:

// Your server (Node.js example)
const response = await fetch('https://api.lomi.africa/charge/card', {
  method: 'POST',
  headers: {
    'X-API-KEY': process.env.LOMI_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000, // Amount in smallest currency unit (e.g., 10000 XOF)
    currency_code: 'XOF',
    customer_email: 'customer@example.com',
    customer_name: 'Ada Lovelace',
  }),
});

const body = await response.json();
const clientSecret = body.data.client_secret;
// Pass clientSecret to your frontend

Detailed endpoint docs: Create card charge

Collect Payment (Client-Side)

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

// Initialize Lomi
const lomi = await loadLomi('lomi_pk_your_publishable_key');

// Create payment elements
const elements = lomi.elements({ clientSecret });
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

// Handle form submission
form.addEventListener('submit', async (e) => {
  e.preventDefault();

  const { error } = await lomi.confirmPayment({
    elements,
    confirmParams: {
      return_url: 'https://yoursite.com/success',
    },
  });

  if (error) {
    console.error(error.message);
  }
});

import { LomiProvider, LomiCardField, useLomi } from '@lomi/react-native';

function App() {
  return (
    <LomiProvider publishableKey="lomi_pk_your_publishable_key">
      <PaymentScreen />
    </LomiProvider>
  );
}

function PaymentScreen() {
  const { confirmPayment } = useLomi();

  const handlePay = async () => {
    const { error } = await confirmPayment(clientSecret, {
      paymentMethodType: 'Card',
    });

    if (error) {
      console.error(error.message);
    }
  };

  return (
    <>
      <LomiCardField
        postalCodeEnabled={false}
        style={{ width: '100%', height: 50 }}
      />
      <Button title="Pay" onPress={handlePay} />
    </>
  );
}

See the full guide: Embed checkout widget.

import { loadLomiCheckout } from '@lomi./embed';

loadLomiCheckout({
  checkoutUrl: session.checkout_url,
  mode: 'modal',
  onComplete: (payload) => {
    console.log(payload.transactionId, payload.hasDigitalDeliverables);
  },
});

For declarative inline embeds, use data-lomi-checkout-url (or data-lomi-session-id) on a container element, then load the IIFE bundle (dist/lomi.js) or import the npm package.

API reference

Payment Intent Endpoint

POST https://api.lomi.africa/charge/card

Parameter	Type	Required	Description
`amount`	number	Yes	Amount in smallest currency unit
`currency_code`	string	No	Currency code (XOF, EUR, USD). Defaults to `XOF`
`currency`	string	No	Backward-compatible alias of `currency_code`
`customer_email`	string	No	Customer's email address
`customer_name`	string	No	Customer's full name
`description`	string	No	Description shown on receipt
`metadata`	object	No	Custom key-value pairs

Response:

{
  "success": true,
  "data": {
    "id": "pi_abc123",
    "client_secret": "pi_abc123_secret_xyz",
    "amount": 152,
    "currency": "eur",
    "original_amount": 10000,
    "original_currency": "XOF",
    "status": "requires_payment_method"
  }
}

Webhooks

After a successful payment, lomi. sends a webhook to your configured endpoint:

{
  "event": "PAYMENT_SUCCEEDED",
  "data": {
    "transaction_id": "txn_abc123",
    "amount": 10000,
    "currency": "XOF",
    "status": "completed",
    "metadata": {}
  }
}

See Webhooks Documentation for setup details.

Testing

Use your test API keys (lomi_pk_test_... and lomi_sk_test_...) against https://sandbox.api.lomi.africa to test payments without processing real transactions.

For sandbox test card numbers, mobile money (Wave, MTN MoMo), hosted checkout QA, and test balances, see Sandbox payments.

lomi. Payment Elements

On this page