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
UseBillionsApi 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.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. OnAsyncBillionsApi, 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
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
Useget_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.