LakiPay

https://lakipay.co/docs
Admin
LakiPay is a unified payment gateway that enables businesses to accept local and international...
Tokens:26,092
Snippets:229
Trust Score:4.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install LakiPay JavaScript SDK

Source: https://lakipay.co/docs/sdks

Installation commands for the LakiPay JavaScript SDK using various package managers.

```bash
npm install lakipay-js-sdk
# or
yarn add lakipay-js-sdk
# or
pnpm add lakipay-js-sdk
# or
npm install github:lakipay-co/lakipay-js-sdk
```

--------------------------------

### Settlement Math Example

Source: https://lakipay.co/docs/lakiconnects/fees

Illustrates the calculation of platform fees and net merchant amounts for a transaction.

```text
gross_amount         = 25,000 ETB
platform_fee         = 25,000 × 0.05 = 1,250 ETB
merchant_net         = 25,000 - 1,250 = 23,750 ETB

→ Connected merchant wallet credited: 23,750 ETB
→ Master merchant wallet credited:     1,250 ETB
→ Derived MASTER_FEE transaction created, linked via parent_transaction_id
```

--------------------------------

### Settlement Webhook Schema

Source: https://lakipay.co/docs/lakiconnects/webhooks

Example JSON payload for a settlement.approved event.

```json
{
  "event": "settlement.approved",
  "idempotency_key": "evt_def456ghi789",
  "occurred_at": "2025-10-02T14:00:00Z",
  "data": {
    "object": "settlement",
    "id": "wd_321fedcba098",
    "connected_account_id": "cm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 47500,
    "status": "approved"
  }
}
```

--------------------------------

### Handle Payment Webhooks in JavaScript

Source: https://lakipay.co/docs/payment-expiry

Example webhook handler demonstrating how to verify events and process terminal statuses like SUCCESS, FAILED, or CANCELLED.

```javascript
// Verify RSA-2048 signature first (see /docs/webhooks)
app.post('/webhooks/lakipay', (req, res) => {
  const { event, transaction_id, reference, status } = req.body;

  if (event === 'DEPOSIT') {
    if (status === 'SUCCESS') {
      // Payment completed – fulfill order, update DB
    } else if (status === 'FAILED' || status === 'CANCELLED') {
      // Expired / failed / cancelled – release hold, notify customer
      // Optionally create a new payment with a fresh reference
    }
  }

  res.status(200).send('OK');
});
```

--------------------------------

### Connected Account Webhook Schema

Source: https://lakipay.co/docs/lakiconnects/webhooks

Example JSON payload for a connected_account.approved event.

```json
{
  "event": "connected_account.approved",
  "idempotency_key": "evt_abc123def456",
  "occurred_at": "2025-10-01T09:10:00Z",
  "data": {
    "object": "connected_account",
    "id": "cm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "master_merchant_id": "mm_9f8e7d6c-b5a4-3210-fedc-ba9876543210",
    "kyc_status": "approved"
  }
}
```

--------------------------------

### GET /api/v2/lakiconnect/connected-accounts/webhook-settings

Source: https://lakipay.co/docs/lakiconnects/webhooks

Retrieves the current webhook configuration settings for connected accounts.

```APIDOC
## GET /api/v2/lakiconnect/connected-accounts/webhook-settings

### Description
Retrieves the current webhook settings for connected accounts.

### Method
GET

### Endpoint
/api/v2/lakiconnect/connected-accounts/webhook-settings

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your live API key.
```

--------------------------------

### Direct Payment Request and Response

Source: https://lakipay.co/docs/lakiconnects/payments

Example JSON payload for a direct payment request and the corresponding successful response.

```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": "251 XXXXXXXX",
  "redirects": {
    "failed": "https://yourplatform.com/payment/failed",
    "success": "https://yourplatform.com/payment/success"
  },
  "reference": "your-unique-reference-id",
  "tag": "ORDER_123"
}
```

```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
}
```

--------------------------------

### Example Signed Webhook Payload

Source: https://lakipay.co/docs/webhooks

A sample JSON payload received from LakiPay, including the signature field used for verification.

```json
{
  "amount": "0.970000",
  "callbackUrl": "https://webhook.site/c4b766e9-5f83-4081-9404-a79575270315",
  "event": "DEPOSIT",
  "lakipayTxnId": "c65452ba-73c8-480a-9a87-c924448a4133",
  "merchantId": "bcb55506-0777-456a-8c1a-b4615bf6682d",
  "message": "Process service request successfully.",
  "providerTxId": "CJD7FSBRER",
  "referenceId": "61fasdgdag22fh1fdaaa880",
  "signature": "Q3ghkA3T5k9pcby+F2NfHEafLeyVBSorpdusGSLaewCZSIPX0NniqQEZAyghd+NdUIPW/r/d2kpq+5+sIhOHbe/lp4wLLuBQ2DIDqD/HPLYCOouZONcDWizGEeTn0tE+/sZrySIWWgLXFVaFo2ME2x4OLyiSFoYIUDJa4eZysSfVSIkuYiaOcriuScWfLHiRaeF1UZ3kl1fxzTEnsjRi9A+Nqqg9YUbTolJ8WoQz2q+SI6pmZ6JPHjCGea0df56JztF7kj91NfB5EJkVmG7K565u5+CRsgxt33VoL1mPpqF9VtWHll0KBsvoH4BBxVo1DvmKMcE3WEyPay+uu1aApg==",
  "status": "SUCCESS",
  "timestamp": "2025-10-13T01:52:06.102109294Z",
  "userId": "f9a6f163-481e-4573-bda2-76edb609a5e6"
}
```

--------------------------------

### Transaction API Responses

Source: https://lakipay.co/docs/api-reference

Example JSON responses for successful transaction retrieval and error scenarios.

```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"
  }
}
```

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

--------------------------------

### Hosted Checkout Request Body

Source: https://lakipay.co/docs/api-reference

Example JSON payload for creating a hosted checkout session with supported payment mediums.

```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"
  ]
}
```

--------------------------------

### Hosted Checkout Request and Response

Source: https://lakipay.co/docs/lakiconnects/payments

Example JSON payload for a hosted checkout request and the corresponding successful response containing the payment URL.

```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": "251 XXXXXXXX",
  "redirects": {
    "failed": "https://yourplatform.com/payment/failed",
    "success": "https://yourplatform.com/payment/success"
  },
  "reference": "your-unique-reference-id",
  "supported_mediums": [
    "MPESA",
    "CBE",
    "OROMIA_BANK"
  ]
}
```

```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
}
```

--------------------------------

### GET /api/v2/lakiconnect/connected-accounts/fee-config

Source: https://lakipay.co/docs/lakiconnects/fees

Retrieves the fee configuration. If X-Connected-Merchant-ID is provided, it returns the resolved configuration for that specific merchant; otherwise, it returns the master default.

```APIDOC
## GET /api/v2/lakiconnect/connected-accounts/fee-config

### Description
Retrieves the fee configuration for the platform or a specific connected account.

### Method
GET

### Endpoint
/api/v2/lakiconnect/connected-accounts/fee-config

### Parameters
#### Query Parameters
- **X-API-Key** (header) - Required - API authentication key.
- **X-Connected-Merchant-ID** (header) - Optional - The ID of the connected merchant to retrieve a resolved configuration for.
```

--------------------------------

### Withdrawal Request Examples

Source: https://lakipay.co/docs/withdrawals

Standard withdrawal request using cURL. Bank-specific withdrawals like OROMIA_BANK or AWASH require an additional account_number field.

```bash
curl -X POST https://api.lakipay.co/api/v2/payment/withdrawal \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "amount": 500.00,
    "currency": "ETB",
    "phone_number": "251 XXXXXXXX",
    "medium": "TELEBIRR",
    "reference": "WITHDRAW-12345",
    "callback_uri": "https://yourwebsite.com/webhook"
  }'
```

```bash
curl -X POST https://api.lakipay.co/api/v2/payment/withdrawal \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "amount": 500.00,
    "currency": "ETB",
    "phone_number": "251 XXXXXXXX",
    "medium": "OROMIA_BANK",
    "account_number": "1000123456789",
    "reference": "WITHDRAW-12345",
    "callback_url": "https://yourwebsite.com/webhook"
  }'
```

--------------------------------

### Initialize LakiPay SDK

Source: https://lakipay.co/docs/sdks

Configure the SDK instance with your API keys and environment settings. Do not expose API keys in browser-side code.

```javascript
import { LakipaySDK } from "lakipay-js-sdk";

const sdk = new LakipaySDK({
  apiKey: "pk_test_xxx:sk_test_xxx", // PUBLICKEY:SECRETKEY
  environment: "production",            
  timeoutMs: 20000,
  logRequests: true,
});
```

--------------------------------

### Create a Connected Account

Source: https://lakipay.co/docs/lakiconnects/onboarding

Submit business, user, bank, and configuration data to initialize a new connected merchant.

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

```text
X-API-Key: <your_master_api_key>
Content-Type: application/json
```

```json
{
  "bank_accounts": [
    {
      "account_number": "1000283746512",
      "bank_name": "Commercial Bank of Ethiopia"
    }
  ],
  "business": {
    "business_registration_number": "REG-123456",
    "business_type": "company",
    "industry_category": "retail",
    "tin": "TIN-987654"
  },
  "configuration": {
    "price_config": {
      "fee_model": "FREE",
      "fee_value": 0
    }
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "First",
    "last_name": "Last",
    "password": "StrongPassword123!",
    "password_hint": "Owner portal login",
    "phone_number": "+251 XXXXXXXX",
    "phone_prefix": "+251",
    "title": "Owner"
  }
}
```

--------------------------------

### GET /lakiconnect/connected-accounts/:id

Source: https://lakipay.co/docs/lakiconnects/api-reference

Retrieve a single connected account by ID.

```APIDOC
## GET /lakiconnect/connected-accounts/:id

### Description
Retrieve a single connected account. Returns merchant core details plus associated bank accounts and their statuses.

### Method
GET

### Endpoint
/lakiconnect/connected-accounts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the connected account
```

--------------------------------

### GET /lakiconnect/connected-accounts

Source: https://lakipay.co/docs/lakiconnects/api-reference

List connected accounts with support for pagination and filtering.

```APIDOC
## GET /lakiconnect/connected-accounts

### Description
List connected accounts. Supports filters such as page, page_size, status, created_from, created_to, and q. Response includes merchant details, configuration, and pagination metadata.

### Method
GET

### Endpoint
/lakiconnect/connected-accounts

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number
- **page_size** (number) - Optional - Items per page
- **status** (string) - Optional - Account status
- **created_from** (string) - Optional - Start date filter
- **created_to** (string) - Optional - End date filter
- **q** (string) - Optional - Search query
```

--------------------------------

### Initiate a Direct Payment Request

Source: https://lakipay.co/docs/direct-payments

Standard request format for initiating a payment via providers like TELEBIRR.

```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": "251 XXXXXXXX",
    "medium": "TELEBIRR",
    "description": "Payment for order #12345",
    "reference": "ORDER-12345",
    "callback_uri": "https://yourwebsite.com/webhook"
  }'
```

--------------------------------

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

Source: https://lakipay.co/docs/lakiconnects/payments

Retrieves the details and current status of a specific settlement.

```APIDOC
## GET /api/v2/lakiconnect/connected-accounts/settlements/:withdrawId

### Description
Retrieves the status and details of a specific settlement to track state transitions.

### Method
GET

### Endpoint
/api/v2/lakiconnect/connected-accounts/settlements/:withdrawId

### Parameters
#### Path Parameters
- **withdrawId** (string) - Required - The unique identifier of the settlement.

#### Request Headers
- **X-Connected-Merchant-Id** (string) - Required - The UUID of the connected merchant.
```

--------------------------------

### Create a checkout session with cURL

Source: https://lakipay.co/docs/hosted-checkout

Use this request to initiate a payment session. Ensure the X-API-Key header is included and the request is made from your backend.

```bash
curl -X POST https://api.lakipay.co/api/v2/payment/checkout \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-publickey:your-secretkey" \
  -d '{
    "amount": 1000.5,
    "currency": "ETB",
    "phone_number": "251 XXXXXXXX",
    "reference": "ORDER123456",
    "description": "Payment for order #123",
    "callback_url": "https://example.com/callback",
    "redirects": {
      "success": "https://example.com/success",
      "failed": "https://example.com/failed"
    },
    "supported_mediums": ["MPESA", "TELEBIRR", "CBE"]
  }'
```

--------------------------------

### GET /api/v2/lakiconnect/connected-accounts

Source: https://lakipay.co/docs/lakiconnects/onboarding

Retrieves a list of connected accounts with support for filtering and pagination.

```APIDOC
## GET /api/v2/lakiconnect/connected-accounts

### Description
Retrieves a list of connected accounts. Supports filters such as page, page_size, status, created_from, created_to, and q. The response includes merchant details, configuration, and pagination metadata.

### Method
GET

### Endpoint
/api/v2/lakiconnect/connected-accounts

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1).
- **page_size** (integer) - Optional - Results per page.
- **status** (string) - Optional - Filter by account status.
- **created_from** (string) - Optional - RFC3339 or YYYY-MM-DD start date.
- **created_to** (string) - Optional - RFC3339 or YYYY-MM-DD end date.
- **q** (string) - Optional - Full-text search (name, email).
```

--------------------------------

### Configure Webhook Settings

Source: https://lakipay.co/docs/lakiconnects/onboarding

Set a webhook URL and secret to receive real-time updates regarding account and settlement events.

```bash
POST /api/v2/lakiconnect/connected-accounts/webhook-settings
```

```json
{
  "webhook_enabled": true,
  "webhook_url": "https://example.com/webhooks/lakiconnect"
  "webhook_secret": "your_secret_key"
}
```

--------------------------------

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

Source: https://lakipay.co/docs/lakiconnects/payments

Retrieves a list of registered settlement bank accounts for a connected merchant.

```APIDOC
## GET /api/v2/lakiconnect/connected-accounts/settlements/banks

### Description
Retrieves the list of registered settlement bank accounts for a specific connected merchant.

### Method
GET

### Endpoint
/api/v2/lakiconnect/connected-accounts/settlements/banks

### Parameters
#### Request Headers
- **X-Connected-Merchant-Id** (string) - Required - The UUID of the connected merchant.
```

--------------------------------

### Configure API Environment

Source: https://lakipay.co/docs/getting-started

Use these base settings to connect to the LakiPay API v2.

```text
Base URL: https://api.lakipay.co
API Version: v2
```

--------------------------------

### GET /api/v2/lakiconnect/connected-accounts/wallet

Source: https://lakipay.co/docs/lakiconnects/fees

Retrieves the current wallet balance and status for a specific connected merchant.

```APIDOC
## GET /api/v2/lakiconnect/connected-accounts/wallet

### Description
Fetches the wallet details for a connected merchant.

### Method
GET

### Endpoint
/api/v2/lakiconnect/connected-accounts/wallet

### Parameters
#### Query Parameters
- **X-API-Key** (header) - Required - API authentication key.
- **X-Connected-Merchant-ID** (header) - Required - The ID of the connected merchant.

### Response
#### Success Response (200)
- **connected_merchant_id** (string) - The merchant ID.
- **balance** (number) - Current available balance.
- **currency** (string) - Currency code.
- **pending_balance** (number) - Pending balance amount.
- **updated_at** (string) - Timestamp of last update.
```

--------------------------------

### Initiate Payout Request

Source: https://lakipay.co/docs/lakiconnects/payments

Endpoint for moving funds from a merchant wallet to a specified medium.

```bash
POST /api/v2/payment/withdrawal
```

--------------------------------

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

Source: https://lakipay.co/docs/api-reference

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

```APIDOC
## GET /api/v2/payment/transaction/{id}

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

### Method
GET

### Endpoint
/api/v2/payment/transaction/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The transaction ID returned by the Direct Payment or Hosted Checkout APIs.
```

--------------------------------

### Create Settlement

Source: https://lakipay.co/docs/lakiconnects/payments

Initiate a fund transfer from the merchant wallet to a registered bank account.

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

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

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

--------------------------------

### Configure Environment Variables

Source: https://lakipay.co/docs/lakiconnects/authentication

Store sensitive credentials and environment-specific URLs in a .env file to avoid hardcoding.

```bash
# .env.example (never commit real keys)
LAKICONNECT_BASE_URL=https://api.lakipay.co
LAKICONNECT_API_KEY=lk_pub_xxxxxxxx:lk_sec_xxxxxxxx
LAKICONNECT_TEST_MERCHANT_ID=<connected_merchant_uuid>
```

--------------------------------

### Hosted Checkout Endpoint and Headers

Source: https://lakipay.co/docs/lakiconnects/payments

The endpoint and required headers for creating a hosted checkout session.

```bash
POST /api/v2/payment/checkout
```

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

--------------------------------

### Direct Payment Endpoint and Headers

Source: https://lakipay.co/docs/lakiconnects/payments

The endpoint and required headers for initiating a direct payment request.

```bash
POST /api/v2/payment/direct
```

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

--------------------------------

### GET /api/v2/lakiconnect/connected-accounts/:id

Source: https://lakipay.co/docs/lakiconnects/onboarding

Retrieves core details for a single connected account, including bank account information.

```APIDOC
## GET /api/v2/lakiconnect/connected-accounts/:id

### Description
Returns the merchant core details plus associated bank accounts and their statuses.

### Method
GET

### Endpoint
/api/v2/lakiconnect/connected-accounts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the connected account.
```

--------------------------------

### Retrieve Fee Configuration

Source: https://lakipay.co/docs/lakiconnects/fees

Fetches the fee configuration for either the master default or a specific connected merchant.

```bash
# Master default
GET /api/v2/lakiconnect/connected-accounts/fee-config
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxx

# Per-connected resolved config
GET /api/v2/lakiconnect/connected-accounts/fee-config
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxx
X-Connected-Merchant-ID: cm_a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

--------------------------------

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

Source: https://lakipay.co/docs/api-reference

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

```APIDOC
## GET /api/v2/payment/transaction/ref/{reference}

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

### Method
GET

### Endpoint
/api/v2/payment/transaction/ref/{reference}

### Parameters
#### Path Parameters
- **reference** (string) - Required - The unique reference ID you passed in the Direct Payment or Hosted Checkout request.

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **data** (object) - Transaction details object

#### Response Example
{
  "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"
  }
}
```

--------------------------------

### POST /payment/direct

Source: https://lakipay.co/docs/lakiconnects/api-reference

Initiate a direct payment attributed to a connected merchant.

```APIDOC
## POST /payment/direct

### Description
Initiate a direct payment attributed to a connected merchant.

### Method
POST

### Endpoint
/payment/direct
```

--------------------------------

### Execute USD Payment Request

Source: https://lakipay.co/docs/direct-payments

Initiate a direct payment request using cURL. Ensure the currency is set to USD and the medium is CYBERSOURCE.

```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": "251 XXXXXXXX",
    "medium": "CYBERSOURCE",
    "description": "International payment",
    "reference": "INTL-12345",
    "merchant_pays_fee": false,
    "callback_uri": "https://yourwebsite.com/webhook"
  }'
```

--------------------------------

### Webhook Signature Verification

Source: https://lakipay.co/docs/lakiconnects/webhooks

This section provides code examples for verifying the signature of a webhook payload to ensure it originated from LakiPay.

```APIDOC
## POST /webhook

### Description
Endpoint to receive and verify LakiPay payment callbacks. The payload must be verified using the provided public key and the signature field.

### Method
POST

### Endpoint
/webhook

### Request Body
- **signature** (string) - Required - The base64 encoded RSA-SHA256 signature of the canonicalized payload.
- **[other fields]** (mixed) - Required - The payment data fields included in the callback.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates the signature was verified successfully.

#### Error Response (401)
- **error** (string) - Indicates the signature verification failed.
```

--------------------------------

### POST /payment/checkout

Source: https://lakipay.co/docs/lakiconnects/api-reference

Create a hosted checkout session.

```APIDOC
## POST /payment/checkout

### Description
Create a hosted checkout session optionally tied to a connected merchant.

### Method
POST

### Endpoint
/payment/checkout
```

--------------------------------

### sdk.payments.createHostedCheckout

Source: https://lakipay.co/docs/sdks

Creates a hosted checkout session that redirects customers to a LakiPay-hosted payment page.

```APIDOC
## sdk.payments.createHostedCheckout

### Description
Generates a URL for a hosted checkout session.

### Parameters
- **amount** (number) - Required - The checkout amount.
- **currency** (string) - Required - The currency code.
- **description** (string) - Optional - Description of the checkout.
- **reference** (string) - Required - Unique order reference.
- **phone_number** (string) - Optional - Customer phone number.
- **callback_url** (string) - Optional - Webhook URL.
- **redirects** (object) - Optional - Success and failed redirect URLs.
- **supported_mediums** (array) - Optional - List of allowed payment methods.

### Response
- **checkout_url** (string) - The URL to redirect the customer to.
- **reference** (string) - The provided order reference.
- **status** (string) - The current status of the checkout session.
```

--------------------------------

### Initiate Awash Bank Payment

Source: https://lakipay.co/docs/direct-payments

Uses the same payload structure as other providers, requiring only the medium to be set to AWASH.

```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": "251 XXXXXXXX",
    "medium": "AWASH",
    "description": "Payment for order #12345",
    "reference": "ORDER-12345",
    "callback_url": "https://yourwebsite.com/webhook"
  }'
```

--------------------------------

### Initiate Direct Payment with Node.js

Source: https://lakipay.co/docs/code-examples

Uses the axios library to send a POST request to the LakiPay direct payment endpoint. Requires a valid API key and callback URI for transaction processing.

```javascript
const axios = require('axios');

async function processPayment() {
  try {
    const response = await axios.post(
      'https://api.lakipay.co/api/v2/payment/direct',
      {
        amount: 100.00,
        currency: 'ETB',
        phone_number: '251 XXXXXXXX',
        medium: 'MPESA',
        description: 'Payment for order #12345',
        reference: 'ORDER-12345',
        callback_uri: 'https://yourwebsite.com/webhook'
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': 'your-api-key-here'
        }
      }
    );
    
    console.log('Payment initiated:', response.data);
    return response.data;
  } catch (error) {
    console.error('Payment failed:', error.response?.data);
    throw error;
  }
}
```

--------------------------------

### Initiate Oromia Bank Deposit and Verify OTP

Source: https://lakipay.co/docs/direct-payments

Requires a bank account number and subsequent OTP verification using the transaction ID.

```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": "251 XXXXXXXX",
    "redirects": {
      "failed": "https://yourwebsite.com/failed",
      "success": "https://yourwebsite.com/success"
    },
    "reference": "12a44b3f-cad3-4111-9dd7-199cb5291dbe",
    "tag": "OROMIA_BANK"
  }'
```

```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"
```

--------------------------------

### Upload KYC Documents

Source: https://lakipay.co/docs/lakiconnects/onboarding

Submit identity and compliance files using multipart/form-data for a specific connected merchant.

```bash
PUT /api/v2/lakiconnect/connected-accounts/kyc-documents
```

```text
X-API-Key: <your_master_api_key>
X-Connected-Merchant-Id: <connected_merchant_uuid>
Content-Type: multipart/form-data
```

--------------------------------

### Retrieve Webhook Settings Request

Source: https://lakipay.co/docs/lakiconnects/webhooks

API request to fetch current webhook configuration settings.

```bash
GET /api/v2/lakiconnect/connected-accounts/webhook-settings
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Authenticate API Requests with X-API-Key

Source: https://lakipay.co/docs/core-concepts

Include your public and secret key pair in the X-API-Key header for all requests. Keys are case-sensitive and should be kept secure.

```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"
```

--------------------------------

### Success Response Format

Source: https://lakipay.co/docs/direct-payments

The JSON structure returned upon successful payment initiation.

```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"
  }
}
```

--------------------------------

### POST /api/v2/payment/direct

Source: https://lakipay.co/docs/lakiconnects/payments

Initiates a direct payment request to a specific payment medium like Telebirr.

```APIDOC
## POST /api/v2/payment/direct

### Description
Sends a payment request directly to a configured medium such as Telebirr.

### Method
POST

### Endpoint
/api/v2/payment/direct

### Request Body
- **amount** (number) - Required - The payment amount.
- **callback_url** (string) - Required - URL for payment status notifications.
- **currency** (string) - Required - Currency code (e.g., ETB).
- **description** (string) - Optional - Description of the payment.
- **details** (object) - Optional - Itemized payment details.
- **medium** (string) - Required - Payment medium (e.g., TELEBIRR).
- **merchant_pays_fee** (boolean) - Optional - Whether the merchant covers the fee.
- **phone_number** (string) - Required - Customer phone number.
- **redirects** (object) - Optional - Success and failure redirect URLs.
- **reference** (string) - Required - Unique reference ID.
- **tag** (string) - Optional - Custom tag for the order.

### Request Example
{
  "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": "251 XXXXXXXX",
  "redirects": {
    "failed": "https://yourplatform.com/payment/failed",
    "success": "https://yourplatform.com/payment/success"
  },
  "reference": "your-unique-reference-id",
  "tag": "ORDER_123"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **status** (string) - Current transaction status.
- **message** (string) - Status message.
- **reference_id** (string) - Unique reference ID.
- **lakipay_transaction_id** (string) - LakiPay transaction identifier.
- **merchant_pays_fee** (boolean) - Fee payment status.
```

--------------------------------

### POST /api/v2/payment/checkout

Source: https://lakipay.co/docs/lakiconnects/payments

Creates a hosted checkout session where customers can select from multiple payment mediums.

```APIDOC
## POST /api/v2/payment/checkout

### Description
Provides a full payment page hosted by LakiConnect for multi-medium payment selection.

### Method
POST

### Endpoint
/api/v2/payment/checkout

### Request Body
- **accept_tip** (boolean) - Optional - Whether to accept tips.
- **amount** (number) - Required - The payment amount.
- **callback_url** (string) - Required - URL for payment status notifications.
- **currency** (string) - Required - Currency code (e.g., ETB).
- **description** (string) - Optional - Description of the payment.
- **merchant_pays_fee** (boolean) - Optional - Whether the merchant covers the fee.
- **phone_number** (string) - Optional - Customer phone number.
- **redirects** (object) - Optional - Success and failure redirect URLs.
- **reference** (string) - Required - Unique reference ID.
- **supported_mediums** (array) - Required - List of allowed payment mediums.

### Request Example
{
  "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": "251 XXXXXXXX",
  "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
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **status** (string) - Current transaction status.
- **message** (string) - Status message.
- **payment_url** (string) - URL to redirect the customer to.
- **reference_id** (string) - Unique reference ID.
- **lakipay_transaction_id** (string) - LakiPay transaction identifier.
```

--------------------------------

### POST /api/v2/payment/direct

Source: https://lakipay.co/docs/direct-payments

Initiates a direct payment transaction through a specified payment provider.

```APIDOC
## POST /api/v2/payment/direct

### Description
Initiates a payment request through a selected provider. Requires an API key in the X-API-Key header.

### Method
POST

### Endpoint
/api/v2/payment/direct

### Parameters
#### Request Body
- **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, OROMIA_BANK, AWASH, etc.
- **bank_account_number** (string) - Required* - Customer bank account number (required for OROMIA_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

### Response
#### Success Response (200)
- **status** (string) - Status of the request
- **message** (string) - Descriptive message
- **data** (object) - Transaction details including transaction_id, reference, amount, currency, status, medium, and created_at
```

--------------------------------

### sdk.payments.createDirectPayment

Source: https://lakipay.co/docs/sdks

Processes a direct payment through supported providers like MPESA, TELEBIRR, or CBE.

```APIDOC
## sdk.payments.createDirectPayment

### Description
Initiates a direct payment transaction.

### Parameters
- **amount** (number) - Required - The payment amount.
- **currency** (string) - Required - The currency code (e.g., "ETB").
- **phone_number** (string) - Required - The customer's phone number.
- **medium** (string) - Required - The payment provider (e.g., "TELEBIRR", "MPESA").
- **description** (string) - Optional - Description of the payment.
- **reference** (string) - Required - Unique order reference.
- **callback_url** (string) - Optional - URL for webhook notifications.

### Response
- **status** (string) - The current status of the transaction.
- **result** (string) - The outcome of the request.
- **reference** (string) - The provided order reference.
- **transaction_id** (string) - The unique LakiPay transaction ID.
```

--------------------------------

### Verify Webhook Signature in Go

Source: https://lakipay.co/docs/lakiconnects/webhooks

Implementation of HMAC-SHA256 signature verification for Go applications.

```go
import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "fmt"
)

func verifySignature(body []byte, signatureHeader, secret string) bool {
  mac := hmac.New(sha256.New, []byte(secret))
  mac.Write(body)
  expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(expected), []byte(signatureHeader))
}
```

--------------------------------

### POST /api/v2/payment/direct

Source: https://lakipay.co/docs/code-examples

Initiates a direct payment request to the LakiPay API.

```APIDOC
## POST /api/v2/payment/direct

### Description
Initiates a direct payment transaction through the LakiPay platform.

### Method
POST

### Endpoint
https://api.lakipay.co/api/v2/payment/direct

### Request Body
- **amount** (number) - Required - The payment amount.
- **currency** (string) - Required - The currency code (e.g., ETB).
- **phone_number** (string) - Required - The customer's phone number.
- **medium** (string) - Required - The payment medium (e.g., MPESA).
- **description** (string) - Optional - Description of the payment.
- **reference** (string) - Required - Unique reference for the order.
- **callback_uri** (string) - Required - The URL to receive webhook notifications.

### Request Example
{
  "amount": 100.00,
  "currency": "ETB",
  "phone_number": "251 XXXXXXXX",
  "medium": "MPESA",
  "description": "Payment for order #12345",
  "reference": "ORDER-12345",
  "callback_uri": "https://yourwebsite.com/webhook"
}
```

--------------------------------

### Retrieve Transaction by Reference

Source: https://lakipay.co/docs/api-reference

cURL command to fetch transaction details using the merchant-supplied reference ID.

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

--------------------------------

### Verify Webhook Signatures in Java

Source: https://lakipay.co/docs/webhooks

Uses java.security classes to parse the public key and verify the SHA256withRSA signature.

```java
import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.X509EncodedKeySpec;
import java.util.*;
import java.util.stream.Collectors;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class WebhookVerifier {
  public static String createCanonicalString(Map<String, Object> payload) {
    return payload.keySet().stream()
      .filter(key -> !key.equals("signature"))
      .sorted()
      .map(key -> key + "=" + payload.get(key).toString())
      .collect(Collectors.joining("&"));
  }

  public static boolean verifySignature(Map<String, Object> payload, String publicKeyPEM) {
    try {
      String canonicalString = createCanonicalString(payload);
      String signatureStr = (String) payload.get("signature");
      byte[] signatureBytes = Base64.getDecoder().decode(signatureStr);

      String publicKeyContent = publicKeyPEM
        .replace("-----BEGIN PUBLIC KEY-----", "")
        .replace("-----END PUBLIC KEY-----", "")
        .replaceAll("\\s", "");
      byte[] decodedKey = Base64.getDecoder().decode(publicKeyContent);
      X509EncodedKeySpec spec = new X509EncodedKeySpec(decodedKey);
      KeyFactory kf = KeyFactory.getInstance("RSA");
      PublicKey publicKey = kf.generatePublic(spec);

      Signature sig = Signature.getInstance("SHA256withRSA");
      sig.initVerify(publicKey);
      sig.update(canonicalString.getBytes(StandardCharsets.UTF_8));
      return sig.verify(signatureBytes);
    } catch (Exception e) {
      System.err.println("Signature verification failed: " + e.getMessage());
      return false;
    }
  }
}

// Usage in your webhook controller
@PostMapping("/webhook")
public ResponseEntity<?> handleWebhook(@RequestBody Map<String, Object> payload) {
  String publicKey = System.getenv("LAKIPAY_PUBLIC_KEY");
  if (!WebhookVerifier.verifySignature(payload, publicKey)) {
    return ResponseEntity.status(401).body(Map.of("error", "Invalid signature"));
  }
  return ResponseEntity.ok(Map.of("success", true));
}
```
Tokens:
Raw