API Reference

Complete reference documentation for all LakiPay API endpoints, parameters, and response formats.

Direct Payment API

POST/api/v2/payment/direct

Process payments through various payment providers. Supports both local (ETB) and international (USD) currencies.

Branches

No branch_id body field. Branch comes from the API key (or LakiConnect headers). Your main account is addressed by leaving branch out — never by a dashboard location ID.

Branch Management guide →

Complete Parameter Reference

Parameter	Type	Required	Description
amount	decimal	Required	Payment amount with 2 decimal places (e.g., 100.00)
currency	string	Required	"ETB" for local, "USD" for international
phone_number	string	Required	Phone number including country code, without `+` (e.g., `251 XXXXXXXX`)
medium	string	Required	Payment provider: MPESA, TELEBIRR, CBE, ETHSWITCH, OROMIA_BANK, AWASH, CYBERSOURCE
description	string	Optional	Human-readable payment description
reference	string	Required	Unique reference ID (max 100 characters)
callback_url	string	Optional	Webhook URL for payment status updates
redirects	object	Optional	Object with success_url and failure_url
merchant_pays_fee	boolean	Optional	For USD payments: whether merchant absorbs fees

Withdrawal API

POST/api/v2/payment/withdrawal

Initiate withdrawals from your merchant account to customer accounts.

Branches

Same branch rules as direct payment. Debits the branch wallet that matches the key / Connect headers.

Branch Management guide →

Hosted Checkout API

POST/api/v2/payment/checkout

Create a hosted checkout session that LakiPay renders for you, supporting multiple payment mediums with redirect URLs for success and failure.

Branches

Branch is fixed at session create. The hosted pay step does not accept a new branch override.

Branch Management guide →

Example Request Body

json

{
  "amount": 1000.5,
  "callback_url": "https://example.com/callback",
  "currency": "ETB",
  "description": "Payment for order #123",
  "phone_number": "251 XXXXXXXX",
  "redirects": {
    "failed": "https://example.com/failed",
    "success": "https://example.com/success"
  },
  "reference": "ORDER123456",
  "supported_mediums": [
    "MPESA",
    "TELEBIRR",
    "CBE"
  ]
}

Parameter	Type	Required	Description
amount	decimal	Required	Payment amount with 2 decimal places.
currency	string	Required	Currency code (e.g., "ETB").
phone_number	string	Required	Phone number including country code, without leading `+`.
reference	string	Required	Unique reference for this checkout session.
callback_url	string	Optional	Webhook URL where LakiPay sends asynchronous status notifications.
redirects.success	string	Required	URL to redirect the customer to after success.
redirects.failed	string	Required	URL to redirect the customer to after failure.
supported_mediums	array[string]	Required	List of payment mediums to show on the hosted checkout (e.g., MPESA, TELEBIRR, CBE, OROMIA_BANK, AWASH).

Transaction Detail API

GET/api/v2/payment/transaction/{id}

Retrieve full details for a specific transaction by its unique identifier.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The transaction ID returned by the Direct Payment or Hosted Checkout APIs.

Example Request

bash

curl -X GET "https://api.lakipay.co/api/v2/payment/transaction/TXN-123456789" \
  -H "X-API-Key: your-publickey:your-secretkey"

Transaction by Reference API

GET/api/v2/payment/transaction/ref/{reference}

Retrieve full details for a transaction using the merchant reference you supplied when creating the payment.

Path Parameters

Parameter	Type	Required	Description
reference	string	Required	The unique reference ID you passed in the Direct Payment or Hosted Checkout request.

Example Request

bash

curl -X GET "https://api.lakipay.co/api/v2/payment/transaction/ref/ORDER173114" \
  -H "X-API-Key: your-publickey:your-secretkey"

Example Response

json

{
  "success": true,
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "phone_number": "251 XXXXXXXX",
    "reference": "ORDER173114",
    "type": "DEPOSIT",
    "medium": "TELEBIRR",
    "message": "Process service request successfully.",
    "details": {
      "RawMessage": null,
      "Valid": true
    },
    "status": "SUCCESS",
    "base_amount": 10,
    "callback_url": "https://api.lakipay.co/api/v2/payments/webhook",
    "success_url": "https://example.com/success",
    "failed_url": "https://example.com/failed",
    "webhook_received": true,
    "created_at": "2026-07-06T10:54:39.690213Z",
    "updated_at": "2026-07-06T10:54:47.393263Z"
  }
}

Error Response

json

{
  "success": true,
  "data": {
    "message": "Transaction not found for the provided reference"
  }
}

Status Codes

HTTP Status Codes

200 OK

Request successful

400 Bad Request

Invalid request parameters

401 Unauthorized

Invalid or missing API key

500 Internal Server Error

Server error, contact support

Transaction Status Values

SUCCESS

Transaction completed successfully

FAILED

Transaction failed

PENDING

Transaction is being processed

CANCELLED

Transaction was cancelled