settlo-pay-python-sdk

Typed Python SDK (sync and async) for the Settlo Pay API: payments (mobile money, bank, QR), refunds, payouts, beneficiaries, balance, hosted checkout, QR codes and webhook verification.

• Built on httpx; Pydantic v2 response models; py.typed, checked with mypy --strict
• Inputs are validated before any request is sent
• Idempotency keys are generated automatically and reused across retries
• Retries use exponential backoff, only where they cannot duplicate a charge or payout
• HTTPS only, redirects never followed, the API key is never logged, printed or pickled

📖 Full reference: documentation.md, covering every method in sync and async form.

There is no sandbox. sk_test_ and sk_live_ keys both move real money.

Install

pip install settlo-pay-python-sdk

Python 3.10+. Import name: settlopay.

Quick start

from settlopay import SettloPay

client = SettloPay()  # reads SETTLO_API_KEY from the environment

payment = client.payments.create(
    amount=25_000,  # TZS, major units
    method="mobile_money",
    phone="+255712345678",  # E.164
    merchant_reference="ORD-8451",
    idempotency_key="order-8451-pay-1",  # derive from your own record
)
print(payment.id, payment.state)  # pi_..., PENDING_AUTH

Async:

from settlopay import AsyncSettloPay

async with AsyncSettloPay() as client:
    balance = await client.balance.retrieve()
    async for p in client.payments.list_all():
        ...

Resources

Amounts accept int, Decimal or numeric str (floats are accepted but discouraged). Response amounts are Decimal.

Errors

from settlopay import SettloError, UnprocessableEntityError, RateLimitError

try:
    client.payouts.create(amount=50_000, idempotency_key="withdrawal-397")
except UnprocessableEntityError as e:  # business decline
    if e.code == "insufficient_funds":
        ...
except RateLimitError as e:
    print("retry in", e.retry_after)
except SettloError as e:
    print(e, e.request_id)  # quote request_id to Settlo support

The full hierarchy is documented in settlopay/exceptions.py. ValidationError covers both local input checks and the API's 400 responses.

Idempotency and retries

Every create call sends an Idempotency-Key. If you don't pass one, the SDK generates a random key and reuses it on every retry of that call. For payouts and payments, pass your own key derived from your database record. Then a crash-and-restart re-sends the same key, and Settlo returns the original result instead of paying twice.

Default policy (RetryPolicy(max_retries=2)):

Webhooks

from settlopay import verify_webhook, WebhookVerificationError


@app.post("/settlo/webhook")
def webhook():
    try:
        event = verify_webhook(
            request.get_data(),  # RAW bytes
            request.headers.get("Settlo-Signature"),
            os.environ["SETTLO_WEBHOOK_SECRET"],  # full whsec_... string
        )
    except WebhookVerificationError:
        return "", 400
    # Deduplicate on request.headers["Settlo-Event-Id"]; events may arrive out of order.
    enqueue(event)  # respond fast, work later
    return "", 200

Logging

The SDK logs to the settlopay logger: method, path, status, request id and retries. It never logs headers or bodies.

Development

python -m venv .venv && . .venv/bin/activate
pip install --upgrade "pip>=25.1"
pip install -e . --group dev
pre-commit install
pytest                  # unit tests (live tests are deselected)
ruff check . && ruff format --check . && mypy

Live smoke test

Read-only by default (balance, lists, limits, a payout quote):

export SETTLO_API_KEY=sk_...           # from your password manager; never commit it
SETTLO_RUN_LIVE=1 pytest -m live tests/live -v

Add SETTLO_LIVE_PHONE=+2557... SETTLO_ALLOW_MONEY_MOVEMENT=1 to also send one collection prompt to your own phone. Money only moves if you approve it.

Releasing

1. Bump src/settlopay/_version.py, update CHANGELOG.md, merge to main.
2. Run the Publish workflow manually to upload to TestPyPI, then check the install.
3. Tag vX.Y.Z and publish a GitHub Release. The workflow publishes to PyPI via Trusted Publishing (OIDC). No token is stored anywhere.

License

MIT