Payaza Python SDK

Unofficial Python SDK for the Payaza Africa API.

Installation

pip install payaza

For local development:

git clone https://github.com/0xAfterSnow/payaza-python
cd payaza-python
pip install -e ".[dev]"

Quick start

from payaza import Payaza

# Live
client = Payaza(api_key="your-live-key")

# Test / sandbox — uses X-TenantID: test on APIs that require it
client = Payaza(api_key="your-test-key", sandbox=True)

Payaza uses a single base URL (https://api.payaza.africa) with a fixed /live/ path prefix for both environments. Test vs live is controlled by your API key and, where required, X-TenantID.

Authentication headers

The SDK does not attach tenant/product headers globally. Resource methods that need them call client.tenant_headers() or client.product_headers() internally.

See the official authentication guide.

Webhooks

Payaza signs each webhook body with HMAC-SHA512 and sends the Base64 digest in x-payaza-signature. Hash the raw request body with your webhook secret (not Base64-encoded):

from payaza import verify_signature

def handle(raw_body: bytes, signature: str, secret: str) -> None:
    if not verify_signature(raw_body, signature, secret):
        raise PermissionError("invalid webhook signature")

Signed transfers

Accounts activated by Payaza for signed payouts send X-Payaza-Signature on Initiate A Transfer. Pass the same style of secret:

client = Payaza(api_key="your-live-key", payout_secret_key="your-payout-secret")

You can also pass secret_key= on a single client.payouts.initiate_payout(...) call. The SDK hashes the exact JSON body it sends.

Implemented resources

Examples

# Main accounts — balances + payazaAccountReference for payouts
accounts = client.accounts.view_main_accounts()
ngn = next(a for a in accounts["data"] if a["currency"] == "NGN")
account_reference = ngn["payazaAccountReference"]

# Bank codes (requires X-TenantID)
banks = client.misc.get_bank_codes("NGN")

# Name enquiry before payout
details = client.accounts.fetch_account_details(
    currency="NGN",
    bank_code="000013",
    account_number="0123456789",
)

# Initiate transfer — sender is nested into each beneficiary
response = client.payouts.initiate_payout(
    transaction_type="nuban",
    payout_amount=1000,
    transaction_pin=1234,
    account_reference=account_reference,
    currency="NGN",
    country="NGA",
    payout_beneficiaries=[{
        "credit_amount": 1000,
        "account_number": "0123456789",
        "account_name": "John Doe",
        "bank_code": "000013",
        "narration": "Test payout",
        "transaction_reference": "TXN-001",
    }],
    sender={
        "sender_name": "Jane Doe",
        "sender_phone_number": "08012345678",
        "sender_address": "Lagos, Nigeria",
    },
)

Runnable scripts live under examples/.

Development

pip install -e ".[dev]"
pytest --cov=payaza

Contributing

PRs are welcome! Please open an issue first to discuss what you'd like to change.

⚠️ Disclaimer

This is an unofficial SDK and is not affiliated with or endorsed by Payaza Africa Limited. Endpoint paths and request/response shapes are based on the public documentation at docs.payaza.africa — always cross-check against the latest official docs and update accordingly.

License

MIT © Shagbaor Agber