LakiConnect
Payment processing
Overview
LakiConnect extends standard LakiPay payment flows by routing transactions to a connected merchant when the X-Connected-Merchant-Id header is present. The master authenticates with their API key; the connected merchant is identified by the header value.
LakiConnect supports two payment entry points:
- Direct Payment — server-to-server, immediate charge initiation.
- Hosted Checkout — generate a payment session URL; customer completes payment in a browser.
Direct Payment
POST /api/v2/payment/directRequest Headers
X-API-Key: lk_pub_xxxxxxxxxxxxxxxxxxxx:lk_sec_xxxxxxxxxxxxxxxxxxxx
X-Connected-Merchant-Id: cm_a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/jsonRequest Body
{
"amount": 25000,
"currency": "ETB",
"payment_method": "mobile_money",
"mobile_number": "+251911000001",
"description": "Order #ORD-20251001-4892",
"callback_url": "https://yourplatform.com/webhooks/payment",
"metadata": {
"order_id": "ORD-20251001-4892",
"customer_id": "cust_00112233"
}
}Response — 200 OK
{
"transaction_id": "txn_7f6e5d4c-3b2a-1908-7654-321fedcba098",
"status": "pending",
"amount": 25000,
"currency": "ETB",
"merchant_net": 23750,
"master_merchant_fee_net": 1250,
"connected_merchant_id": "cm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"master_merchant_id": "mm_9f8e7d6c-b5a4-3210-fedc-ba9876543210",
"created_at": "2025-10-01T09:00:00Z"
}Hosted Checkout
POST /api/v2/payment/checkoutCreates a hosted checkout session. The X-Connected-Merchant-Id header binds the session to the connected merchant at creation time.
Request Body
{
"amount": 12000,
"currency": "ETB",
"description": "Marketplace purchase – Selam Handcrafts",
"success_url": "https://yourplatform.com/checkout/success",
"cancel_url": "https://yourplatform.com/checkout/cancel",
"metadata": {
"order_id": "ORD-20251001-4893"
}
}Response — 200 OK
{
"checkout_id": "chk_1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"checkout_url": "https://checkout.lakipay.co/chk_1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"expires_at": "2025-10-01T10:00:00Z",
"connected_merchant_id": "cm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending"
}Redirect your customer to checkout_url. The split is resolved server-side from the connected merchant stored on the session — no additional header is required at the customer-facing payment step.
Transaction Status Lifecycle
| Status | Description |
|---|---|
| `PENDING` | Payment initiated; awaiting confirmation. |
| `SUCCESS` | Payment confirmed; wallets credited. |
| `FAILED` | Payment declined or errored. |
Idempotency
All payment creation requests should include an Idempotency-Key header. Retrying a request with the same key within 24 hours returns the original response without creating a duplicate transaction.
Idempotency-Key: order-ORD-20251001-4892-attempt-1What LakiConnect Does NOT Split
POST /payment/withdrawal— connected split is not applied; the optional split argument is omitted.- QR merchant payments — processed without a connected merchant ID.