> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usezentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```bash pip theme={null}
  pip install zentra
  ```

  ```bash poetry theme={null}
  poetry add zentra
  ```
</CodeGroup>

## Configuration

Initialize the client with your API key. You can find your API keys in the [Developer Console](https://api.usezentra.com/developer/signin?callbackUrl=%2Fdeveloper%2Fapi-keys).

```python theme={null}
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

```python theme={null}
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

```python theme={null}
charge = client.payments.charge(
    amount_minor=500000,  # ₦5,000.00
    currency="NGN",
    email="user@example.com",
    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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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.

<CardGroup cols={2}>
  <Card title="GitHub Repo" icon="github" href="https://github.com/zentra/zentra-python">
    View source code
  </Card>

  <Card title="PyPI" icon="python" href="https://pypi.org/project/zentra/">
    Download package
  </Card>
</CardGroup>