Charges

A charge represents a single payment request. This is the only resource in the API — create one, then either wait for a webhook or poll it to find out what happened.

Create a charge

POST/v1/charges/

Creates a new charge and returns a hosted checkout URL.

Request fields

`amount` integerrequired	The amount to charge, in the minor unit of your currency. Must be greater than 0.
`currency` stringoptional	Defaults to your merchant account's configured currency if omitted.
`description` stringoptional	A free-text note shown on the checkout page and in your dashboard.
`reference` stringoptional	Your own identifier for this charge (e.g. an order ID).
`customer_name` stringoptional	Pre-fills the customer's name on the checkout page.
`customer_email` stringoptional	Pre-fills the customer's email on the checkout page.
`customer_phone` stringoptional	Pre-fills the customer's Mobile Money number on the checkout page.
`success_url` stringoptional	Where to redirect the customer after a successful payment.
`cancel_url` stringoptional	Where to redirect the customer if they cancel.
`service_id` stringoptional	Attributes this charge to a specific service under your account. The service must belong to your merchant account.

Example request

Terminal

curl -X POST https://live.lotifinance.com/v1/charges/ \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "description": "Invoice #881",
    "reference": "inv_881",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "success_url": "https://yourapp.com/paid",
    "cancel_url": "https://yourapp.com/cancelled"
  }'

Response fields

`id` stringoptional	Unique charge identifier.
`status` stringoptional	One of pending, processing, completed, failed, cancelled, expired. Always pending immediately after creation.
`amount` integeroptional	Echoes the requested amount.
`currency` stringoptional	The currency used for this charge.
`method` string \| nulloptional	The Mobile Money provider used to pay, once chosen on the checkout page.
`checkout_url` stringoptional	The hosted page to redirect your customer to.
`created_at` datetimeoptional	When the charge was created.
`expires_at` datetimeoptional	30 minutes after creation. The checkout page stops accepting payment after this.
`completed_at` datetime \| nulloptional	Set once the charge reaches completed.

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "amount": 15000,
  "currency": "XAF",
  "description": "Invoice #881",
  "reference": "inv_881",
  "customer_name": "Jane Doe",
  "customer_email": "jane@example.com",
  "customer_phone": null,
  "success_url": "https://yourapp.com/paid",
  "cancel_url": "https://yourapp.com/cancelled",
  "service_id": null,
  "method": null,
  "checkout_url": "https://pay.lotifinance.com/c/a1b2c3d4-...",
  "created_at": "2026-10-02T10:15:00Z",
  "expires_at": "2026-10-02T10:45:00Z",
  "completed_at": null
}

No idempotency key support

The API does not currently support an idempotency key on create. If your request times out, check the charge's final state before retrying to avoid creating a duplicate.

Retrieve a charge

GET/v1/charges/{id}/

Returns the current state of a charge. Use this to poll for completion as an alternative to webhooks.

Terminal

curl https://live.lotifinance.com/v1/charges/a1b2c3d4-.../  \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

Returns the same charge object shown above, with status and method updated to reflect the current state. There is no endpoint to list charges — retrieval is always by id.

Charge statuses

`pending` statusoptional	Created, waiting for the customer to pay.
`processing` statusoptional	The customer has started paying; the provider is confirming it.
`completed` statusoptional	Payment succeeded. completed_at is set and a webhook fires.
`failed` statusoptional	The payment attempt did not succeed.
`cancelled` statusoptional	The customer cancelled on the checkout page.
`expired` statusoptional	No successful payment within 30 minutes of creation.

Authentication

Webhooks