Direct charges

The Charges API allows you to initiate direct payments with specific providers. This is useful when you want to build a custom checkout experience or charge a customer directly without redirecting them to a hosted checkout page immediately (though some providers like Wave may still return a checkout URL).

lomi. Network Operators can add Lomi-Account: acct_... to create card, Wave, or MTN charges for a connected Member Account. The membership must have payment.create.

Create a Wave Charge

Initiate a payment request specifically for Wave Mobile Money.

Endpoint

POST /charge/wave

Request Body

Field	Type	Required	Description
`amount`	`number`	Yes	The amount to charge (minimum 100).
`currency`	`string`	Yes	The currency code (must be `XOF`).
`customer`	`object`	Yes	Customer details object.
`customer.name`	`string`	Yes	Full name of the customer.
`customer.email`	`string`	No	Email address of the customer.
`customer.phoneNumber`	`string`	No	Phone number of the customer (e.g., `+2250102030405`).
`description`	`string`	No	Description of the charge.
`successUrl`	`string`	No	URL to redirect after successful payment.
`errorUrl`	`string`	No	URL to redirect after failed payment.
`environment`	`string`	No	`live` or `test` (defaults to `live`).

curl -X POST "https://api.lomi.africa/charge/wave" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phoneNumber": "+2250707070707"
    },
    "description": "Payment for Service",
    "successUrl": "https://your-site.com/success",
    "errorUrl": "https://your-site.com/error"
  }'

const response = await fetch('https://api.lomi.africa/charge/wave', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': process.env.LOMI_SECRET_KEY!,
  },
  body: JSON.stringify({
    amount: 1000,
    currency: 'XOF',
    customer: {
      name: 'Jane Doe',
      email: 'jane@example.com',
      phoneNumber: '+2250707070707',
    },
    description: 'Payment for Service',
    successUrl: 'https://your-site.com/success',
    errorUrl: 'https://your-site.com/error',
  }),
});

const data = await response.json();

import requests
import os

url = "https://api.lomi.africa/charge/wave"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": os.environ["LOMI_SECRET_KEY"]
}
payload = {
    "amount": 1000,
    "currency": "XOF",
    "customer": {
        "name": "Jane Doe",
        "email": "jane@example.com",
        "phoneNumber": "+2250707070707"
    },
    "description": "Payment for Service",
    "successUrl": "https://your-site.com/success",
    "errorUrl": "https://your-site.com/error"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

Response

Returns a 201 Created status with the Wave session details and checkout URL.

{
  "transactionId": "1a0a4df9-ae73-4776-b955-57522625421c",
  "checkoutUrl": "https://pay.wave.com/c/cos-22txmv4682mee?...",
  "waveSession": {
    "id": "cos-22txmv4682mee",
    "amount": "1000",
    "checkout_status": "open",
    "payment_status": "processing",
    "currency": "XOF",
    "aggregated_merchant_id": "am-1wfm8v3z023p4",
    ...
  }
}

Error Responses

Status	Description
`400`	Bad Request (e.g., missing provider configuration, invalid amount).
`401`	Unauthorized (invalid API Key).
`500`	Internal Server Error (payment provider failure).

Embedded card charge

Create a card payment and return a client_secret for your own checkout UI.

Endpoints

Method	Path
`POST`	`/charge/card`
`GET`	`/charge/card/{id}`
`POST`	`/charge/card/{id}/cancel`

const res = await lomi.charges.createCardCharge({
  amount: 10000,
  currency_code: 'XOF',
  customer_email: 'buyer@example.com',
  customer_name: 'Buyer Name',
});
// res.data.client_secret → confirm on the client with your publishable key

See Create card charge and lomi Payment Elements.

Network example:

curl -X POST "https://api.lomi.africa/charge/card" \
  -H "X-API-KEY: $LOMI_OPERATOR_API_KEY" \
  -H "Lomi-Account: acct_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency_code": "XOF",
    "customer_email": "buyer@example.com",
    "customer_name": "Buyer Name"
  }'

Reference implementation

Minimal runnable demo (Wave, MTN, card via @lomi./sdk Payment Elements) lives in the monorepo:

apps/plugins/references/direct-charge-integration-reference: server proxy, Payment Element UI, and cURL scripts

For hosted checkout sessions instead, see payment-integration-sdk-reference.

MTN direct charge

POST /charge/mtn, same pattern as Wave; see Create MTN charge.

Direct charges

On this page