Data models

This page explains the objects you will see across the merchant-facing API. It is not a dump of every internal schema. If an object only exists for dashboard administration, provider configuration, or lomi. operations, it is intentionally left out of the public reference.

Use the endpoint pages for the exact request and response contract. Use this page when you want the shape and meaning of the objects you will pass around in your integration.

Shared conventions

Field	Meaning
`id`, `*_id`	Stable identifier for an object. Store it in your system when you need to reconcile or fetch the object later.
`amount`, `gross_amount`, `net_amount`, `fee_amount`	Integer amount in the smallest currency unit. For `XOF`, `5000` means 5,000 XOF.
`currency_code`	ISO currency code such as `XOF`, `USD`, or `EUR`.
`metadata`	Your own key-value data. Use it for internal order IDs, user IDs, or reconciliation hints.
`environment`	`test` or `live`. Never mix objects from both environments in the same reconciliation flow.
`created_at`, `updated_at`	ISO 8601 timestamps.

Customer

A customer represents the payer or buyer attached to payments, subscriptions, and portal sessions.

Returned by Customers endpoints and embedded in some payment/subscription responses.

{
  "customer_id": "cus_123",
  "name": "Awa Diop",
  "email": "awa@example.com",
  "phone_number": "+221771234567",
  "country": "SN",
  "metadata": {
    "crm_id": "lead_981"
  },
  "environment": "live",
  "created_at": "2026-02-14T10:30:00.000Z",
  "updated_at": "2026-02-14T10:30:00.000Z"
}

Product and price

A product is what you sell. A price is the amount and billing behavior attached to that product.

Returned by Products, checkout, and subscription flows.

{
  "product_id": "prod_123",
  "name": "Pro plan",
  "description": "Monthly access to the Pro workspace",
  "product_type": "recurring",
  "is_active": true,
  "metadata": {
    "plan_code": "pro"
  },
  "prices": [
    {
      "price_id": "price_123",
      "amount": 15000,
      "currency_code": "XOF",
      "billing_interval": "month",
      "pricing_model": "standard",
      "is_default": true
    }
  ],
  "environment": "live"
}

Checkout session

A checkout session creates a hosted payment page. Your application redirects the customer to the checkout URL, then listens for payment status through redirects and webhooks.

Returned by Checkout sessions.

{
  "id": "cs_123",
  "status": "pending",
  "amount": 15000,
  "currency_code": "XOF",
  "checkout_url": "https://checkout.lomi.africa/cs_123",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "metadata": {
    "order_id": "order_481"
  }
}

Direct charge

A direct charge starts a provider-specific payment without hosted checkout. Use it only when you need to control the payment experience yourself.

Returned by Advanced direct charges.

{
  "id": "ch_123",
  "status": "pending",
  "amount": 5000,
  "currency_code": "XOF",
  "provider_code": "WAVE",
  "payment_method_code": "MOBILE_MONEY",
  "provider_transaction_id": "wave_abc123",
  "metadata": {
    "order_id": "order_481"
  }
}

Subscription

A subscription represents recurring access for a customer. Subscription endpoints include both plan-level operations and customer-scoped subscription operations.

Returned by Subscriptions.

{
  "subscription_id": "sub_123",
  "customer_id": "cus_123",
  "product_id": "prod_123",
  "status": "active",
  "amount": 15000,
  "currency_code": "XOF",
  "billing_frequency": "monthly",
  "current_period_start": "2026-02-01T00:00:00.000Z",
  "current_period_end": "2026-03-01T00:00:00.000Z",
  "metadata": {
    "workspace_id": "wk_42"
  }
}

Transaction

A transaction is the ledger-style record of money movement. Use it for reconciliation, reporting, and support investigations.

Returned by Transactions.

{
  "transaction_id": "txn_123",
  "gross_amount": 5000,
  "fee_amount": 125,
  "net_amount": 4875,
  "currency_code": "XOF",
  "transaction_type": "payment",
  "status": "completed",
  "provider_code": "WAVE",
  "provider_transaction_id": "wave_abc123",
  "metadata": {
    "order_id": "order_481"
  },
  "created_at": "2026-02-14T10:31:04.000Z"
}

Balance

A balance shows available and pending money by currency. Use it before creating payouts or when reconciling settlement timing.

Returned by Balances.

{
  "currency_code": "XOF",
  "available_amount": 275000,
  "pending_amount": 42500,
  "reserved_amount": 0,
  "updated_at": "2026-02-14T10:45:00.000Z"
}

Webhook endpoint

A webhook endpoint tells lomi. where to deliver events. Store the signing secret securely and verify every incoming event.

Returned by Webhooks.

{
  "id": "wh_123",
  "url": "https://example.com/webhooks/lomi",
  "authorized_events": ["PAYMENT_SUCCEEDED", "PAYMENT_FAILED"],
  "is_active": true,
  "secret": "whsec_...",
  "created_at": "2026-02-14T10:30:00.000Z"
}

Webhook delivery log

A delivery log is an operational record for one webhook attempt. Use it to debug retries, failed endpoints, and event delivery issues.

Returned under Webhooks.

{
  "id": "wdl_123",
  "webhook_id": "wh_123",
  "event_type": "PAYMENT_SUCCEEDED",
  "delivery_status": "failed",
  "response_status": 500,
  "attempt_count": 3,
  "next_retry_at": "2026-02-14T10:45:00.000Z"
}

Error

Errors return a human-readable message and, when available, structured details your application can log.

{
  "error": {
    "message": "Invalid API key",
    "details": "The provided API key is invalid or does not exist"
  }
}

See Errors for status codes and common failure patterns.

Data models

On this page