pycentry 0.1.0

Official Python SDK for the Centry payment API

Centry Python SDK

Official Python SDK for the Centry payment API.

pip install centry

Quick start

Public checkout (customer-facing)

from centry import Client

client = Client(api_key="cen_your_api_key")

session = client.checkout.create(
    amount="5000.00",
    currency="NGN",
    reference="ORDER-12345",
    success_url="https://yoursite.com/success",
    cancel_url="https://yoursite.com/cancel",
    webhook_url="https://yoursite.com/webhooks/centry",
    customer={"email": "[e-mail]"},
)

print(session.checkout_url)  # Redirect customer here

Merchant API (server-to-server)

from centry import Client

merchant = Client(merchant_key="mk_test_...")

# Create a payin (collection)
payin = merchant.payins.create(
    country_code="UG",
    amount=50000,
    payment_method="mobile_money",
    gateway="mtn_momo",
    customer_name="Jane Doe",
    customer_phone="[phone]",
    reference="ORDER-1234",
    create_invoice=True,   # auto-create invoice in your ERP on completion
)

print(payin.id, payin.status, payin.net_amount)

# Send a payout (disbursement)
payout = merchant.payouts.create(
    country_code="ZA",
    amount=250000,
    payment_method="bank_transfer",
    gateway="netcash",
    recipient_name="Acme Suppliers",
    recipient_account_number="1234567890",
    recipient_bank_name="Standard Bank",
    create_bill=True,       # auto-create bill in your ERP on completion
)

# Check balance
for balance in merchant.balance.list():
    print(f"{balance.currency_code}: {balance.available}")

Both keys in one client

client = Client(
    api_key="cen_...",
    merchant_key="mk_live_...",
)
client.checkout.create(...)
client.payins.create(...)
client.balance.list()

Custom base URL (local development)

client = Client(
    merchant_key="mk_test_...",
    base_url="http://localhost:8000",
)

Auth: two kinds of keys

Key	Prefix	Used for	Where to find
API Key	cen_...	Customer-facing checkout	Org admin → Integrations
Merchant Key	mk_test_... / mk_live_...	Server-to-server payins, payouts, balance	Merchant admin → API Keys

The same client can hold both — the SDK picks the right one per endpoint.

Error handling

All errors inherit from CentryError. The SDK maps HTTP status to specific exceptions:

from centry import Client, ValidationError, AuthenticationError, CentryError

try:
    payin = client.payins.create(
        country_code="UG",
        amount=-100,  # invalid
        payment_method="mobile_money",
    )
except ValidationError as e:
    print("Bad input:", e.message)
except AuthenticationError:
    print("Key is invalid or expired")
except CentryError as e:
    print(f"HTTP {e.status_code}: {e.message}")

Exceptions:

• ValidationError (400) — invalid parameters or insufficient balance
• AuthenticationError (401) — invalid or expired key
• PermissionError (403) — missing permission / IP not whitelisted / country mismatch
• NotFoundError (404) — resource does not exist
• RateLimitError (429) — slow down
• ServerError (5xx) — unexpected server failure
• NetworkError — transport-level failure (DNS, timeout, etc.)

Response types

All responses are dataclasses with typed fields:

from centry import Balance, Payin, Payout, CheckoutSession

session: CheckoutSession = client.checkout.create(...)
session.checkout_url
session.session_token

payin: Payin = merchant.payins.create(...)
payin.id
payin.net_amount  # str — parse to Decimal if you need arithmetic
payin.centry_fee
payin.gateway_fee
payin.invoice_number  # populated after completion if create_invoice=True

Development

git clone https://github.com/centry/centry-python
cd centry-python
pip install -e ".[dev]"
pytest

Links

• API reference
• Example app (Next.js)
• Issues