Skip to main content
The Python SDK supports Python 3.10 or newer and uses httpx 0.27 or newer. It provides synchronous and asynchronous clients.

Python SDK on GitHub

Browse the source code, examples, releases, and issue tracker.

Installation

Synchronous client

Use BillionsApi as a context manager so its HTTP client is closed automatically:

Withdrawals and refunds

Both clients sign these requests automatically. Generate and store a distinct UUID for each intended money operation before calling the SDK. Reuse the same ID and payload if the response is lost.
The request_id argument is optional, but passing one lets you safely retry an uncertain operation. On AsyncBillionsApi, await each of these methods. See Withdrawals and refunds for the request rules and response fields.

Asynchronous client

AsyncBillionsApi exposes the same operations as coroutines:

Available methods

Both clients expose the same methods. On AsyncBillionsApi, await HTTP operations; signature verification is synchronous.
get_countries() returns country codes and names. estimate_fees() returns amount, finalPrice, fee, and merchantReceiveAmount, with optional summaryFee. The default API host is https://api.billions.works, and the default public API version is v1. You can override both or inject a custom httpx.Client or httpx.AsyncClient.

Verify a webhook signature

Set secret_key to the original API secretKey when creating the client. The method parses JSON text or bytes, canonicalizes it according to RFC 8785 JCS, and verifies HMAC-SHA256. It accepts jcs-sha256=<hex> or a plain hex digest. On AsyncBillionsApi, get_invoice_from_webhook() must be awaited. Use the authenticated invoice response for payment decisions even when the signature is valid.

Process webhook events

Use get_invoice_from_webhook() for both intermediate invoice.status_changed events and final invoice.paid events:

Verify a paid event

verify_invoice_paid() accepts the current webhook envelope and legacy callback objects. It retrieves the authoritative invoice from the API, requires completed status, and compares the callback status and paid amount. Decimal forms such as 100, 100.0, and 100.000000000000000000 are treated as equivalent.

Errors

Transport errors use status_code == 0.