Python SDK

Official Zentra library for Python applications

The Zentra Python SDK provides convenient access to the Zentra API from applications written in the Python language.

The reviewed public HTTP surface for this SDK is transfers, webhooks, virtual accounts, payments, cards, and tenant-enabled identity. Customers, wallets, and other generated helpers may still exist for compatibility or draft use cases, but they are not the default reviewed public API path.

pip

pip install zentra

poetry add zentra

Configuration

Initialize the client with your API key. You can find your API keys in the Developer Console.

import os
from zentra import Zentra

client = Zentra(
    secret_key=os.environ["ZENTRA_SECRET_KEY"],
    base_url="https://sandbox.api.usezentra.com",
)

Resources

The SDK maps to reviewed API resources as follows:

• client.payments: Payment processing
• client.transfers: Bank transfers
• client.virtual_accounts: Virtual bank accounts
• client.cards: Card issuing
• client.identity: KYC verification
• client.webhooks: Webhook handling

Examples

Create a Transfer

try:
    transfer = client.transfers.create(
        amount=500000,
        bank_code="058",
        account_number="0123456789",
        account_name="Vendor Settlement Account",
        narration="Vendor payout",
        reference="TRF_12345",
    )
    print(f"Queued transfer: {transfer['reference']}")
except Exception as e:
    print(f"Error: {e}")

Create Charge

charge = client.payments.charge(
    amount_minor=500000,  # ₦5,000.00
    currency="NGN",
    email="[e-mail]",
    reference="ORD_12345",
    capture_mode="customer_action_required"
)

verified = client.payments.verify(charge["reference"])
print(f"Status: {verified['status']}")

Verify Webhook Signature

Securely verify incoming webhooks from Zentra:

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks", methods=["POST"])
def zentra_webhook():
    signature = request.headers.get("X-Zentra-Signature")
    payload = request.get_data(as_text=True)
    
    if client.webhooks.verify_signature(payload, signature, webhook_secret):
        event = client.webhooks.construct_event(payload, signature, webhook_secret)
        # Process webhook logic here using event
        return "Verified", 200
    
    return "Invalid signature", 400

Error Handling

The SDK raises exceptions for API errors:

from zentra.errors import APIError, AuthenticationError, InvalidRequestError

try:
    client.payments.verify("INVALID_REF")
except InvalidRequestError as e:
    print(f"Bad request: {e}")
except AuthenticationError:
    print("Check your API key")
except APIError as e:
    print(f"Zentra API error: {e}")

Async Support

For concurrent workloads, run the sync client in background tasks:

import asyncio
from zentra import Zentra

async def main():
    client = Zentra(
        secret_key="sk_sandbox_...",
        base_url="https://sandbox.api.usezentra.com",
    )
    
    # Run requests concurrently
    transfer_task = asyncio.to_thread(client.transfers.get, "TRF_12345")
    payment_task = asyncio.to_thread(client.payments.verify, "ORD_12345")
    
    transfer, payment = await asyncio.gather(transfer_task, payment_task)
    
    print(f"Transfer: {transfer['status']}, payment: {payment['status']}")

asyncio.run(main())

Source Code

Only use the official library. The source code is available on GitHub.

GitHub Repo

View source code

PyPI

Download package