Direct Payments API

Process payments directly through various payment providers. Support for local currency (ETB) and international payments (USD).

Overview

The Direct Payment API allows you to initiate payments through multiple payment providers. Payments can be processed in ETB (local) or USD (international via CYBERSOURCE).

Endpoint

POST /api/v2/payment/direct

Authentication

X-API-Key header required

Local Currency Payments (ETB)

Supported Providers

MPESA

TELEBIRR

CBE Birr

ETHSWITCH

OROMIA_BANK

AWASH

KACHA

GADAA_BANK

Request Parameters

Parameter	Type	Required	Description
amount	decimal	Required	Payment amount (e.g., 100.00)
currency	string	Required	Currency code: "ETB" for local payments
phone_number	string	Required	Customer phone in E.164 format (+251...)
medium	string	Required	Payment provider: MPESA, TELEBIRR, CBE Birr, ETHSWITCH, OROMIA_BANK, AWASH, KACHA, GADAA_BANK, etc.
bank_account_number	string	Required*	Customer bank account number (required for OROMIA_BANK and GADAA_BANK)
tag	string	Optional*	Usually set to OROMIA_BANK for Oromia deposits
description	string	Optional	Payment description
reference	string	Required	Unique reference ID for tracking
callback_uri	string	Optional	Webhook URL for payment status updates
redirects	object	Optional	Success/failure redirect URLs

Example Request

bash

curl -X POST https://api.lakipay.co/api/v2/payment/direct \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "amount": 100.00,
    "currency": "ETB",
    "phone_number": "2519XXXXXXXX",
    "medium": "TELEBIRR",
    "description": "Payment for order #12345",
    "reference": "ORDER-12345",
    "callback_uri": "https://yourwebsite.com/webhook"
  }'

Oromia Bank Deposit Example

Oromia Bank deposits use live settlement — funds flow through LakiPay and are automatically settled into the Oromia bank account you configured in the Bank Accounts section of your LakiPay dashboard. There is no manual payout step; once the customer confirms with their OTP, the money lands in your settlement account.

Include the customer's bank_account_number in your request and set medium to OROMIA_BANK. After initiating the payment, complete verification with the OTP endpoint.

bash

curl -X POST https://api.lakipay.co/api/v2/payment/direct \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "bank_account_number": "1000123456789",
    "amount": 1,
    "callback_url": "https://yourwebsite.com/webhook",
    "currency": "ETB",
    "description": "Payment description",
    "medium": "OROMIA_BANK",
    "merchant_pays_fee": false,
    "phone_number": "2519XXXXXXXX",
    "redirects": {
      "failed": "https://yourwebsite.com/failed",
      "success": "https://yourwebsite.com/success"
    },
    "reference": "12a44b3f-cad3-4111-9dd7-199cb5291dbe",
    "tag": "OROMIA_BANK"
  }'

OTP verification (use the transaction_id from the response):

bash

curl -X POST https://api.lakipay.co/api/v2/payment/transaction/{transaction_id}/verify/otp/{otp} \
  -H "X-API-Key: your-api-key-here"

Awash Bank Example

AWASH uses the same payload shape as TELEBIRR/CBE — only change the medium.

bash

curl -X POST https://api.lakipay.co/api/v2/payment/direct \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "amount": 100.00,
    "currency": "ETB",
    "phone_number": "2519XXXXXXXX",
    "medium": "AWASH",
    "description": "Payment for order #12345",
    "reference": "ORDER-12345",
    "callback_url": "https://yourwebsite.com/webhook"
  }'

Kacha Example

KACHA uses the same payload shape as TELEBIRR/CBE — only change the medium. No bank account number is required; the customer confirms via USSD push on their phone.

bash

curl -X POST https://api.lakipay.co/api/v2/payment/direct \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "amount": 100.00,
    "currency": "ETB",
    "phone_number": "2519XXXXXXXX",
    "medium": "KACHA",
    "description": "Payment for order #12345",
    "reference": "ORDER-12345",
    "callback_url": "https://yourwebsite.com/webhook"
  }'

Success Response

json

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

USD International Payments (via CYBERSOURCE)

Important Requirements

• USD payments are only available via CYBERSOURCE provider
• Your account must be enabled for USD transactions
• Contact support to enable USD payment processing
• Currency must be set to "USD"

Additional Parameters

Parameter	Type	Description
currency	string	Must be "USD" for international payments
medium	string	Must be "CYBERSOURCE"
merchant_pays_fee	boolean	false: customer pays the transaction fee (deducted from or added on top of their payment). true: you (the merchant) absorb the fee — customer is charged only the stated amount.

Example USD Payment Request

bash

curl -X POST https://api.lakipay.co/api/v2/payment/direct \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "amount": 50.00,
    "currency": "USD",
    "phone_number": "2519XXXXXXXX",
    "medium": "CYBERSOURCE",
    "description": "International payment",
    "reference": "INTL-12345",
    "merchant_pays_fee": false,
    "callback_uri": "https://yourwebsite.com/webhook"
  }'

Success Response

HTTP 200 OK

json

{
  "success": true,
  "status": "PENDING",
  "message": "Payment request processed successfully",
  "reference_id": "xxxxxxxxxxxx",
  "lakipay_transaction_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "medium": "CYBERSOURCE",
  "currency": "USD",
  "amount": 2
}

Callback Notifications

LakiPay sends asynchronous status updates to the callback_url you provide.

Example callback payload

json

{
  "reference_id": "xxxxxxxxxxxx",
  "status": "SUCCESS",
  "message": "Payment completed successfully",
  "amount": 2,
  "currency": "USD",
  "medium": "CYBERSOURCE",
  "transaction_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp": "2025-11-06T12:34:56Z"
}

Payment Providers

MPESA

Mobile money payment provider

ETB

TELEBIRR

Ethio Telecom mobile money service

ETB

CBE Birr

Commercial Bank of Ethiopia payment service

ETB

ETHSWITCH

Ethiopian banking switch network

ETB

OROMIA_BANK

Oromia Bank - bank account deposit with OTP verification

ETB

AWASH

Awash Bank mobile payment

ETB

KACHA

Kacha mobile money payment

ETB

GADAA_BANK

Gadaa Bank payment option

ETB

CYBERSOURCE

International payment gateway for USD transactions

USD