LakiPayConnect

Payment processing

Direct payments, hosted checkout, payouts, settlements, and wallet balance.

Overview

Once a connected merchant has been onboarded and verified, your platform uses the endpoints in this guide to run day-to-day money movement flows on their behalf. These flows fall into three groups:

  • Collecting customer payments — direct or hosted checkout.
  • Sending payouts — to mobile money or similar channels.
  • Creating settlements — to registered bank accounts.

The master authenticates with their API key; the connected merchant is identified by the X-Connected-Merchant-Id header on all operations covered here.

Direct Payment

Direct payments send a payment request directly to a configured medium such as Telebirr.

bash
POST /api/v2/payment/direct

Request Headers

text
X-API-Key: <your_master_api_key>
Content-Type: application/json
Accept: application/json
X-Connected-Merchant-Id: <connected_merchant_uuid>

Request Body

json
{
  "amount": 1,
  "callback_url": "https://yourplatform.com/api/lakiconnect/payments/callback",
  "currency": "ETB",
  "description": "Payment for order #123",
  "details": {
    "item_description": "Sample item",
    "item_id": "1234567890",
    "item_name": "Item name",
    "item_quantity": 1
  },
  "medium": "TELEBIRR",
  "merchant_pays_fee": false,
  "phone_number": "0912345678",
  "redirects": {
    "failed": "https://yourplatform.com/payment/failed",
    "success": "https://yourplatform.com/payment/success"
  },
  "reference": "your-unique-reference-id",
  "tag": "ORDER_123"
}

Response

json
{
  "success": true,
  "status": "PENDING",
  "message": "Telebirr USSD Push request sent successfully",
  "reference_id": "3c69530b-45ff-4c9f-82d6-c2d4fc7a70be",
  "lakipay_transaction_id": "6b743288-4a31-429d-a846-c20bbb52ac9d",
  "merchant_pays_fee": false
}

Integration notes

  • Persist reference_id and lakipay_transaction_id for reconciliation.
  • Update order status based on callbacks to the configured callback_url.
  • Use the redirects URLs for browser-based flows where the customer is redirected after payment.

Hosted Checkout

Hosted checkout provides a full payment page hosted by LakiConnect, where customers can choose from multiple mediums (for example, MPESA, bank gateways).

bash
POST /api/v2/payment/checkout

Request Headers

text
X-API-Key: <your_master_api_key>
Content-Type: application/json
Accept: application/json
X-Connected-Merchant-Id: <connected_merchant_uuid>

Request Body

json
{
  "accept_tip": false,
  "amount": 10,
  "callback_url": "https://yourplatform.com/api/lakiconnect/payments/callback",
  "currency": "ETB",
  "description": "Payment for order #123",
  "merchant_pays_fee": false,
  "phone_number": "0912345678",
  "redirects": {
    "failed": "https://yourplatform.com/payment/failed",
    "success": "https://yourplatform.com/payment/success"
  },
  "reference": "your-unique-reference-id",
  "supported_mediums": [
    "MPESA",
    "CBE",
    "OROMIA_BANK"
  ]
}

Response

json
{
  "success": true,
  "status": "PENDING",
  "message": "Hosted checkout created successfully",
  "payment_url": "https://checkout.lakipay.co/checkout/3d2444a3-fe5a-4479-b2b6-931c906eff28",
  "reference_id": "a4cbdcfe-05ea-469c-a574-b3ffab09c023",
  "lakipay_transaction_id": "3d2444a3-fe5a-4479-b2b6-931c906eff28",
  "merchant_pays_fee": false
}

Redirect your customer to payment_url. Upon completion, LakiConnect sends notifications to callback_url and optionally redirects the customer to your configured success or failure URLs.

Transaction Status Lifecycle

StatusDescription
`PENDING`Payment initiated; awaiting confirmation.
`SUCCESS`Payment confirmed; wallets credited.
`FAILED`Payment declined or errored.

Payouts (Withdrawals to Payment Channels)

Payouts move funds from a connected merchant's wallet to a specific medium (for example, Telebirr).

bash
POST /api/v2/payment/withdrawal

Request Headers

text
X-API-Key: <your_master_api_key>
Content-Type: application/json
Accept: application/json
X-Connected-Merchant-Id: <connected_merchant_uuid>

Request Body

json
{
  "amount": 1,
  "callback_url": "https://yourplatform.com/api/lakiconnect/payouts/callback",
  "currency": "ETB",
  "medium": "TELEBIRR",
  "merchant_pays_fee": false,
  "phone_number": "0912345678",
  "reference": "WD-123456789"
}

Insufficient funds response

json
{
  "success": false,
  "message": "failed to lock withdrawal amount: insufficient funds: available balance is 0.00 ETB"
}

Always check wallet balance before initiating payouts and display clear error messages to merchants when payouts cannot be processed.

Settlements

Transfer funds from the wallet to a registered settlement bank account belonging to the merchant.

Settlement Bank Management

bash
GET /api/v2/lakiconnect/connected-accounts/settlements/banks

Request Headers

text
X-Connected-Merchant-Id: <connected_merchant_uuid>

The response contains:

  • connected_merchant_id
  • banks — each with id, merchant_id, bank_name, account_number, status, created_at, and updated_at

You must use one of these bank id values when creating a settlement.

Create Settlement

bash
POST /api/v2/lakiconnect/connected-accounts/settlements

Request Headers

text
X-API-Key: <your_master_api_key>
X-Connected-Merchant-Id: <connected_merchant_uuid>

Request Body

json
{
  "amount": 1,
  "business_bank_id": "e82128f4-2f91-40d3-9626-58e5019fe830"
}

Response fields

  • id — settlement ID
  • connected_merchant_id
  • amount and status (for example, PENDING)
  • Embedded business_bank details
  • created_at and updated_at timestamps

Retrieve Settlement

bash
GET /api/v2/lakiconnect/connected-accounts/settlements/:withdrawId

Request Headers

text
X-Connected-Merchant-Id: <connected_merchant_uuid>

Returns the same settlement structure and should be used to track settlement state transitions (for example, from PENDING to COMPLETED or FAILED).

Wallet Balance

Each connected merchant has an associated wallet that tracks their funds across all payment, payout, and settlement activity. The wallet balance is the source of truth when deciding whether payouts or settlements can be initiated — your platform should check this balance before debiting or instructing transfers.

What the wallet tracks

  • Available balance — funds that can be withdrawn via payouts or settlements.
  • Locked amounts — funds reserved for in-progress payouts or settlements.
  • Total fees and gross amounts processed — cumulative fee deductions and gross transaction volume for reconciliation.
bash
GET /api/v2/lakiconnect/connected-accounts/wallet

Request Headers

text
X-Connected-Merchant-Id: <connected_merchant_uuid>

The response includes fields such as balance (available balance), amount (gross amount processed), total_fee, locked_amount, currency, wallet_type, and timestamps. Use this endpoint to:

  • Display up-to-date balances in merchant dashboards
  • Validate whether payouts or settlements can be initiated — compare the requested amount against the available balance before calling withdrawal or settlement endpoints
  • Support reconciliation and risk checks

Continue reading

Platform fees & revenue sharing

Configure fee models, overrides, and understand settlement math.