lomi.
Payments

Lomi Payment Elements

Accept payments directly in your app with Lomi's white-labeled payment infrastructure.

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:

MethodUse Case
JS SDK (@lomi/js)Web applications using vanilla JavaScript or any framework
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/js
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/payment-intents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LOMI_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000, // Amount in smallest currency unit (e.g., 10000 XOF)
    currency: 'XOF',
    customer_email: 'customer@example.com',
  }),
});

const { clientSecret } = await response.json();
// Pass clientSecret to your frontend

Collect Payment (Client-Side)

import { loadLomi } from '@lomi/js';

// 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} />
    </>
  );
}
<!DOCTYPE html>
<html>
<body>
  <div id="lomi-checkout"></div>
  
  <script type="module">
    import { loadLomiCheckout } from '@lomi/embed';
    
    loadLomiCheckout({
      elementId: 'lomi-checkout',
      sessionId: 'cs_your_checkout_session_id',
      publicKey: 'lomi_pk_your_publishable_key',
    });
  </script>
</body>
</html>

The Embedded Checkout preserves Lomi's full UI/UX and automatically resizes to fit its container.

API Reference

Payment Intent Endpoint

POST https://api.lomi.africa/payment-intents
ParameterTypeRequiredDescription
amountnumberYesAmount in smallest currency unit
currencystringYesCurrency code (XOF, EUR, USD)
customer_emailstringNoCustomer's email address
customer_namestringNoCustomer's full name
descriptionstringNoDescription shown on receipt
metadataobjectNoCustom key-value pairs

Response:

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

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_...) to test payments without processing real transactions.

Test Card Numbers:

CardNumber
Successful payment4242 4242 4242 4242
Declined4000 0000 0000 0002
Requires authentication4000 0025 0000 3155

Use any future expiry date and any 3-digit CVC.

Discount Coupons

Create and manage promotional discount codes.

Webhooks

Configure webhook endpoints for real-time event notifications.

On this page

Lomi Payment Elements
Overview
Installation
Quick Start
Get Your API Keys
Create a Payment Intent (Server-Side)
Collect Payment (Client-Side)
API Reference
Payment Intent Endpoint
Webhooks
Testing