LakiConnect | LakiPay Docs

Overview

Onboarding is a prerequisite for all other LakiConnect operations. A connected merchant must first be created, webhook settings configured, and KYC documents submitted to complete verification.

Create the account — submit business, user, bank, and configuration data.
Configure webhook settings — set a webhook URL to receive real-time account and settlement events.
Upload KYC documents — submit identity and compliance files for review.

After submission, the KYC status is updated and exposed via connected account retrieval endpoints (for example, the kycStatus field). Your platform should enforce business rules such as enabling payments and payouts only when KYC is approved.

Step 1 — Create a Connected Account

bash

POST /api/v2/lakiconnect/connected-accounts

Request Headers

text

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

Request Body

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": "0912345678",
    "phone_prefix": "+251",
    "title": "Owner"
  }
}

Key considerations

bank_accounts associates a bank account that will later be used for settlements.
business contains legal entity information required for compliance and reporting.
configuration.price_config defines initial fee settings; this can be updated later via fee configuration endpoints.
configuration.webhook can set up your webhook URL and secret to receive asynchronous events.
user represents the main contact or login for this connected merchant.

The response includes a connected merchant ID (UUID). Store this value and use it as X-Connected-Merchant-Id in subsequent API calls.

Step 2 — Configure Webhook Settings

Configure your webhook address to receive real-time updates about all connected accounts under your master merchant account. Once set up, the system sends event notifications whenever important changes happen, such as:

Connected account KYC status changes (pending, approved, rejected)
Settlement events (initiation, success, failure)
Connected account status updates and operational changes

bash

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

Request Headers

Header	Purpose
`Accept: application/json`	Response format.
`Content-Type: application/json`	Sending JSON data.
`X-API-Key`	Your master merchant authentication key.

Request Body

json

{
  "webhook_enabled": true,
  "webhook_url": "https://example.com/webhooks/lakiconnect"
}

Step 3 — Upload KYC Documents

bash

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

Request Headers

text

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

Form Fields

Field	Type	Description
`tin`	File	Tax identification certificate.
`business_license`	File	Official business registration/license.
`national_id`	File	National ID of the owner/director.

After submission, the KYC status for the merchant is updated and exposed via connected account retrieval endpoints. Gate payments and payouts until KYC is in an approved state.

KYC Status Lifecycle

Status	Description
`pending`	Account created; KYC documents not yet submitted.
`under_review`	Documents submitted; under manual or automated review.
`approved`	KYC passed; account is active and can receive payments.
`rejected`	KYC failed; master receives a connected account status webhook.

List Connected Accounts

Endpoint

Property	Value
Method	`GET`
Path	`/lakiconnect/connected-accounts`

bash

GET /api/v2/lakiconnect/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, which can be used to power internal admin dashboards.

Query Parameters

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

Retrieve Single Connected Account

Endpoint

Property	Value
Method	`GET`
Path	`/lakiconnect/connected-accounts/:id`

bash

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

Returns the merchant core details plus associated bank accounts and their statuses. Your platform can use this for detailed merchant views, KYC status display, and bank account verification.

Recommended Onboarding Practices

Centralize configuration — keep baseUrl, API keys, and merchant IDs in secure configuration layers, not in code.
Persist IDs for correlation — store connected_merchant_id (and later reference_id, lakipay_transaction_id, and settlement IDs) for reconciliation and support.
Use webhooks for asynchronous flows — configure webhook URLs at onboarding time; a common address for all connected accounts is recommended.
Gate features by KYC status — only enable payments and payouts when KYC is in an approved state.
Validate balances before debits — query wallet balance before payouts or settlements to avoid insufficient-fund errors.
Implement idempotency at the business layer — use stable reference values for retries so duplicate calls do not create duplicate business actions.

Payment processing

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