Getting started

lenco-py is an unofficial Python SDK for the Lenco API v2. This page gets you from installation to your first transfer.

Prerequisites

• Python 3.11 or newer
• A Lenco API token — request one from support@lenco.co

Installation

pip install lenco-py

For card collections, install the card extra:

pip install "lenco-py[card]"

Create a client

WARNING

Store the token in an environment variable — never in source control. If a token is ever exposed, contact support@lenco.co for a new one immediately.

import os
from lenco import LencoClient

client = LencoClient(token=os.environ["LENCO_API_TOKEN"])

Use AsyncLencoClient with the same arguments in async code — see Framework recipes.

Make your first transfer

Send 20 ZMW to a mobile money wallet:

transfer = client.transfers.to_mobile_money(
    account_id="your-account-uuid",  # see client.accounts.list()
    amount=20.00,
    reference="order-1001",
    phone="0977433571",
    operator="airtel",
    country="zm",
)

print(transfer.status)           # "successful", "pending", or "failed"
print(transfer.lenco_reference)  # Lenco's own reference

WARNING

Lenco always returns HTTP 200 for transfer initiation. The HTTP status tells you the request was accepted. transfer.status tells you the outcome. See Error handling.

Choose a unique reference

reference is how you correlate API responses, webhooks, and status checks with your own records. Generate one per transaction (an order ID, a UUID) and store it before calling the API. Only -, ., _ and alphanumeric characters are allowed.

Next steps

• Handling webhooks — receive final transaction statuses
• Error handling — handle failures safely
• Framework recipes — Django and FastAPI
• API reference — every resource in detail