amatopay

Official Python client for the AmatoPay payment gateway API — collect mobile-money payments (alias push or QR), track payments and deliveries, and verify webhooks.

Install

uv add amatopay
# or
pip install amatopay

Quickstart

import amatopay

client = amatopay.AmatoPay(api_key="sk_live_...")  # or set AMATOPAY_API_KEY

session = client.checkout.create_session(
    order_number="ORDER-1001",
    amount="100000.00",
    currency="BIF",
    payer_alias="+25779000000",
    return_url="https://merchant.bi/payment/result",
)
print(session["checkout_url"])  # send the payer here, or redirect them

AmatoPay() with no arguments reads AMATOPAY_API_KEY (and AMATOPAY_BASE_URL, if you're pointed at a non-default environment) from the environment — handy for keeping secrets out of code.

What's here

• client.ping() — confirm your API key works and check onboarding/activation status.
• client.checkout — verify a payer alias, create alias-push or QR payment sessions, poll a hosted checkout session's status.
• client.payments — list/retrieve payments, confirm delivery with a payer's secure code.
• client.fees — preview the fee for a given amount before creating a session.
• client.deliveries — track fulfillment (mark shipped/delivered) and buyer-protection claims.
• amatopay.webhooks — verify and parse signed webhook deliveries.

See examples/ for runnable scripts, and the developer docs for the full API reference.

Handling errors

Every non-2xx response raises a typed exception, all subclasses of amatopay.APIError:

try:
    client.checkout.create_session(...)
except amatopay.ValidationError as e:
    print(e.body)  # {"payer_alias": ["This alias is not payable."]}
except amatopay.PermissionError:
    print("Merchant not active yet, or missing a required capability.")

Verifying webhooks

import amatopay

@app.route("/webhooks/amatopay", methods=["POST"])
def amatopay_webhook():
    try:
        event = amatopay.webhooks.construct_event(
            request.get_data(),  # raw bytes — verify before parsing JSON yourself
            request.headers["AmatoPay-Signature"],
            endpoint_secret,  # your whsec_... for this endpoint
        )
    except amatopay.SignatureVerificationError:
        return "", 400

    if event["type"] == "payment.paid":
        ...
    return "", 200

Development

This project uses uv.

uv sync              # install deps + dev tools into .venv
uv run pytest        # run the test suite
uv run ruff check .  # lint
uv build             # build the sdist + wheel into dist/

License

MIT