Core Concepts

Authentication

X-API-Key Header

All API requests must include your API credentials in the X-API-Key header.

LakiPay uses a PUBLICKEY:SECRETKEY combination as the value of X-API-Key, for example: pk_live_xxx:sk_live_xxx.

bash

curl -X POST https://api.lakipay.co/api/v2/payment/direct \
  -H "X-API-Key: your-publickey:your-secretkey" \
  -H "Content-Type: application/json"

Important

• API keys are case-sensitive
• Never share your API key publicly
• Rotate keys regularly for security
• Use different keys for test and production

Branches

API keys can target your main account or a secondary location. Switch the dashboard JWT to the target branch, then create the key — a branch_id field on the create body is ignored. Prefer one key per POS / store.

Branch Management guide →

Request Format

HTTP Methods

LakiPay API uses standard HTTP methods:

POSTCreate new resources (payments, withdrawals)

GETRetrieve transaction status and information

Content Type

All requests must use application/json content type:

text

Content-Type: application/json

Request Body Structure

Request bodies are JSON objects. Example direct payment request:

json

{
  "amount": 100.00,
  "currency": "ETB",
  "phone_number": "251 XXXXXXXX",
  "medium": "MPESA",
  "description": "Payment description",
  "reference": "unique-reference-id",
  "callback_url": "https://yourwebsite.com/webhook"
}

Response Format

Success Response

A successful response (HTTP 200) contains:

json

{
  "status": "SUCCESS",
  "message": "Payment initiated successfully",
  "data": {
    "transaction_id": "TXN-123456789",
    "reference": "unique-reference-id",
    "amount": 100.00,
    "currency": "ETB",
    "status": "PENDING",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
status	string	SUCCESS or ERROR
message	string	Human-readable message
data	object	Transaction details
transaction_id	string	Unique transaction identifier
reference	string	Your reference ID

Error Handling

Error Response Format

Error responses follow this structure:

json

{
  "error": {
    "message": "string",
    "type": "string"
  },
  "success": true
}

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

Common Error Codes

Error Code	Description	Solution
INVALID_API_KEY	API key is invalid or missing	Check your API key in headers
INVALID_AMOUNT	Amount format is incorrect	Use decimal format (e.g., 100.00)
INVALID_PHONE	Phone number format is invalid	Use E.164 format (+251...)
INSUFFICIENT_BALANCE	Insufficient account balance	Top up your account
PROVIDER_ERROR	Payment provider error	Retry or contact support

Currency and Amount Formatting

Supported Currencies

ETB (Ethiopian Birr)

Local currency for Ethiopian payment providers

Format: 100.00

USD (US Dollar)

International currency via CYBERSOURCE

Format: 100.00

Amount Format

Amounts must be provided as decimal numbers with up to 2 decimal places:

100.00✓ Valid

100✗ Invalid (missing decimals)

100.123✗ Invalid (too many decimals)