Wholly Crypto Python SDK

The official Python client for your self-hosted Wholly Crypto merchant API. Create invoices, check payments, manage accepted assets and verify IPN/webhooks.

Python 3.10+. Standard library only, with no runtime dependencies. SDK 1.0.0 targets API v1, tested against merchant 3.5.0. SDK and merchant versions are independent.

Install

python -m pip install whollycrypto

Use a virtual environment for your application. Import the package as whollycrypto.

Create an invoice

Use your installation's API domain, not its merchant-console or checkout domain. Create a credential in Settings → API access with read/write access to the project.

Find both UUIDs under Project → Stores → select store → Basic → API IDs. Copy Project API ID and Store API ID, not the readable project/store identifiers. Projects and stores are created in the console; the public API does not list or create them.

import os
from whollycrypto import Client

# Persist this key AND the exact payload with your order before the request.
# Reuse the same key, credential and payload if the response is lost.
idempotency_key = "order-1042-payment-attempt-1"

with Client("https://api.your-domain.com", os.environ["WHOLLY_API_TOKEN"]) as client:
    result = client.create_invoice(
        "11111111-1111-4111-8111-111111111111",  # Your Project API ID
        "22222222-2222-4222-8222-222222222222",  # Your Store API ID
        {
            "amount": "49.90",  # A string, never a float
            "currency": "EUR",
            "order_id": "order-1042",
            "email": "customer@example.com",
            "description": "Annual plan",
            "ipn_url": "https://your-shop.com/wholly/ipn",
            "redirect_url": "https://your-shop.com/orders/1042",
            "cancel_url": "https://your-shop.com/cart",
        },
        idempotency_key=idempotency_key,
    )

public_invoice_id = result["data"]["public_id"]
checkout_url = result["links"]["checkout"]

The UUIDs above are placeholders. Return checkout_url to your customer, or redirect from your server. Never put an API token in browser JavaScript, HTML, checkout URLs or source control. A return/success URL is not proof of payment.

Every API method returns the complete response envelope. Fields such as data, links, pagination and reconciliation's separate top-level fields are preserved. The SDK does not rename fields or round amounts. JSON fractional numbers decode as decimal.Decimal; monetary strings and arbitrarily large JSON integers stay exact.

Check and list payments

Reuse one client per worker/request context, then close it. The default transport reuses its HTTPS connection. Calls are synchronous; run them outside an async event loop or in a thread worker. Do not share a client across concurrent workers, because last_response describes its most recent call.

invoice = client.get_invoice(project_id, public_invoice_id)["data"]
if invoice["status"] == "settled":
    # Match the stored order, amount/currency and project/store first.
    # Fulfil exactly once using your database's transaction/idempotency mechanism.
    pass

page = client.list_invoices(project_id, {
    "store_id": store_id, "status": "settled", "search": "order-1042",
    "limit": 50, "offset": 0,
})

for invoice in client.iter_invoices(project_id, {"status": "settled"}):
    # Each next page is requested only when needed.
    pass

These snippets use an open client. Invoice paths use public_id, not internal id or order_id. processing is not settled. Pages are separate snapshots, so deduplicate by public invoice ID if exporting while new invoices are arriving.

Amounts and invoice options

Amount, spread, tolerance and fixed token prices accept plain decimal strings or Decimal. Floats are rejected for these fields. Decimal values are encoded as plain strings without exponent notation. Other request values use normal JSON types.

from decimal import Decimal

payload = {
    "amount": Decimal("25.00"),
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "expires_in_seconds": 900,
    "language": "de",
    "metadata": {
        "firstname": "Ada", "lastname": "Lovelace",
        "street": "12 Example Street", "street2": "Suite 2", "zip": "10115",
        "city": "Berlin", "country": "Germany", "countryiso2": "DE",
        "company": "Example GmbH", "vatid": "DE123456789",
    },
    "checkout_appearance": {
        "title": "Complete your order", "intro": "Thanks for choosing us.",
        "outro": "Questions? https://your-shop.com/help",
        "intro_font_size": 18, "outro_font_size": 16,
        "theme": "light", "accent_color": "#1768CE",
    },
}

Omitted options inherit store settings. Use {} for objects, not []. An empty checkout_appearance object freezes the resolved store design for that invoice; omitting it keeps normal store appearance behavior. Appearance accepts structured settings, not arbitrary HTML, JavaScript or CSS. The server remains authoritative for currencies, allowed assets, confirmation policy and validation.

Request object keys are sorted for deterministic bytes. List order, strings and decimal precision are preserved. Never switch SDKs/encodings during an invoice retry: the server binds idempotency to the original credential and exact raw JSON bytes. Client.new_idempotency_key() generates a key; you must persist it before use.

Merchant API methods

IDs accept strings or uuid.UUID. See the full API reference and payment-method examples.

update_store_payment_assets() receives the list itself, not an assets wrapper. [] removes all on-chain selections. It does not configure Lightning. Refunds, sends, reconciliation decisions, accounts, exchange credentials and Lightning configuration are console-only; the SDK does not invent public routes for them.

Verify IPN and webhooks

Both use the same signature format. Use the IPN/webhook signing secret from the store configuration, not an API token. Pass the exact raw body as bytes.

from whollycrypto import InvalidSignatureError, parse_notification

try:
    notice = parse_notification(raw_body, request_headers, signing_secret)
except InvalidSignatureError:
    # Return HTTP 400 without logging secrets or the customer's payload.
    raise

# Durably enqueue before returning 2xx. Failed storage must not be acknowledged.
# Persist (configured_project_id, notice.invoice_id, notice.sequence) for deduplication.
# Your worker re-fetches the invoice through the authenticated client before fulfilment.

Verification uses HMAC-SHA256 and a constant-time comparison, with a five-minute past/future clock window. Keep your server clock synchronized. verify_signature() is also available for signature-only checks. parse_notification() additionally validates UUIDs, status and sequence, then returns a readonly Notification payload. notice.invoice_id is the public invoice UUID.

Signatures cover the timestamp and raw body, not event/delivery ID headers. Do not deduplicate using event ID alone: changing it must not let an attacker bypass replay protection, and a forged collision must not suppress a different signed invoice. Use the signed invoice ID and sequence, scoped to your configured project. Keep invoice state monotonic and re-check the authenticated invoice. Event names are not sent in the payload or headers.

The WSGI inbox example verifies before storage, queues durably in private SQLite, handles duplicates and does not acknowledge failed writes. It does not fulfil orders or start a web server. Mount it behind your application's HTTPS server and implement an idempotent worker. The example's private filesystem checks target Linux/POSIX deployments.

Errors, timeouts and retries

from whollycrypto import APIError, Client, Options, TransportError

client = Client("https://api.your-domain.com", token, options=Options(
    timeout_seconds=20, connect_timeout_seconds=5,
    max_retries=1, max_retry_delay_seconds=30,
))
try:
    result = client.get_invoice(project_id, public_invoice_id)
except APIError as error:
    status = error.status_code
    code = error.error_code
    retry_after = error.retry_after  # Seconds or None
    # error.api_message / error.response.body are opt-in private details, not log text.
except TransportError:
    # A timeout does NOT prove invoice creation failed.
    # Retry its original payload with the same stored key and credential.
    pass
finally:
    client.close()

Retries are off by default. With retries enabled, only GETs and invoice creation with its explicit key can retry transient connections or HTTP 429/502/503/504. Other writes never retry automatically. Retries reuse the immutable request and honor Retry-After seconds or a standard HTTP date. Invalid headers or waits longer than the configured limit are surfaced to your queue, never retried early. At most three retries can be enabled. Include attempts/backoff in your worker budget; network timeouts depend on the operating system's DNS/socket behavior.

client.last_response.rate_limit() returns limit, remaining and reset headers when present. last_response is None if the most recent attempted request has no HTTP response. The default limit is 8 MiB per response and 32 KiB per merchant request.

TLS verification is always enabled. No automatic redirects, cookie storage, proxy environment discovery or .netrc lookup. Options(ca_file="/path/to/ca.pem") can trust your private CA without disabling hostname verification. A custom transport receives credentials and must be trusted. Closing a client closes its default transport; injected/shared transports remain caller-owned.

Repr and normal SDK exception messages omit credentials and response bodies. Python debuggers can still inspect private attributes and frame locals: disable local-variable/body capture in production error monitoring and never pickle clients.

Public checkout and Lightning

from whollycrypto import CheckoutClient

with CheckoutClient("https://pay.your-domain.com") as checkout:
    view = checkout.get_invoice(public_invoice_id)
    url = checkout.invoice_url(public_invoice_id)

This separate reader never holds or sends a merchant API token. It also exposes get_preview(project, store=None) and preview_url(project, store=None, state="waiting"). Preview states are illustrative, not evidence of payment. Use the QR and image URLs returned by checkout JSON instead of reconstructing them.

Preserve payment_rail, asset_decimals, destination tags/memos, payment_uri and payable. Lightning BTC uses 11 atomic decimals (millisatoshis); on-chain BTC uses 8. Its payment hash is not an on-chain address. Use the BOLT11/payment URI. The SDK never signs or sends funds.

Development

python -m pip install -e .
python -m unittest discover -s tests -t . -v
python -m pip install build twine
python -m build
python -m twine check dist/*

Tests cover all 17 merchant endpoints, validation, precision, retry identity, HTTP connection reuse, TLS rejection, signature verification and the durable receiver. They use only mocks/disposable loopback servers and SQLite, never live payments. Tests require OpenSSL CLI, SSL and SQLite support. Plain HTTP is available only for explicit Options(allow_insecure_localhost=True) tests on localhost/127.0.0.1/::1; this never disables HTTPS certificate verification.

An optional Python 3.10–3.14 CI template is provided in ci/github-actions.yml. Enabling it requires a maintainer with workflow-write permission. See maintenance notes for API drift checks and release verification.

License

MIT, for this client SDK only. The merchant application and other Wholly Crypto software have their own licenses. No server implementation or private-service code is included.