pycentry 0.1.1

Official Python SDK for the Centry payment API

Centry Python SDK

Official Python SDK for the Centry payment API.

pip install pycentry

The package is published as pycentry on PyPI but imports as centry:

from centry import Client

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