Transactions

The Transactions API allows you to retrieve information about payment transactions associated with your merchant account.

Authentication

Requests require authentication using your API key in the `X-API-Key` header. See the Authentication guide.

The transaction object

Represents a single payment transaction, including details about the amount, status, provider, customer, and related resources. See Data Models for the full structure.

Endpoints

List transactions

Retrieves a list of transactions for the authenticated merchant, with options for filtering and pagination.

Endpoint: `GET /transactions`

Query parameters:

Parameter	Type	Required	Description
`status`	`string` / `array`	No	Filter by transaction status(es). Provide a single status or comma-separated list (e.g., `completed`, `failed,refunded`). Valid statuses: `pending`, `completed`, `failed`, `refunded`, `expired`.
`provider`	`string`	No	Filter by payment provider code (e.g., `ORANGE`, `WAVE`).
`from_date`	`string (ISO8601)`	No	Filter transactions created on or after this date/time (inclusive). Format: `YYYY-MM-DDTHH:mm:ssZ`.
`to_date`	`string (ISO8601)`	No	Filter transactions created on or before this date/time (inclusive). Format: `YYYY-MM-DDTHH:mm:ssZ`.
`limit`	`number`	No	Maximum number of transactions to return (default: 20, max: 100).
`page`	`number`	No	Page number for pagination (default: 1).

Example request (filtering for completed Wave transactions):

GET /transactions example request

GET /transactions?status=completed&provider=WAVE&limit=10
Host: api.lomi.africa
X-API-Key: your_api_key

Example response (200 OK):

GET /transactions response

{
  "success": true,
  "data": [
    {
      "transaction_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
      "organization_id": "0979ec77-9fb1-4c9a-8c55-d7fb6c182c9c",
      "customer_id": "c47ac10b-58cc-4372-a567-0e02b2c3d480",
      "gross_amount": 5000,
      "fee_amount": 125,
      "net_amount": 4875,
      "fee_reference": "STANDARD_FEE",
      "currency_code": "XOF",
      "payment_method_code": "MOBILE_MONEY",
      "provider_code": "WAVE",
      "provider_transaction_id": "prov_trx_12345",
      "transaction_type": "payment",
      "product_id": null,
      "subscription_id": null,
      "status": "completed",
      "description": "Payment for Order #5678",
      "created_at": "2025-04-05T10:30:00.000Z",
      "updated_at": "2025-04-05T10:30:05.000Z",
      "metadata": { "source": "api" }
    }
    // ... more transaction objects
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10
    // "total": 5 // Total count may not always be present
  },
  "environment": "test"
}

Get transaction by ID

Retrieves the details of a specific transaction by its unique ID.

Endpoint: `GET /transactions/{transaction_id}`

Path parameters:

Parameter	Type	Required	Description
`transaction_id`	`string (UUID)`	Yes	The unique identifier of the transaction to retrieve.

Example response (200 OK):

GET /transactions/{id} response

{
  "success": true,
  "data": {
    "transaction_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    // ... all other transaction fields as shown in the list example
    "metadata": { "source": "api" }
  },
  "environment": "test"
}

Error handling

Common errors include `400 Bad Request` for invalid filter parameters or ID format, `401 Unauthorized`, `404 Not Found` if the transaction ID doesn’t exist, and `500 Internal Server Error`. Refer to the Errors guide for general structure and handling.

Checkout sessions Webhooks