SatsRail Python SDK

Official Python SDK for the SatsRail Bitcoin payment API. Accept Bitcoin payments via Lightning Network, on-chain, and USDT.

Installation

pip install satsrail

Requires Python 3.8+.

Quick Start

import satsrail

client = satsrail.SatsRail("sk_live_...")

session = client.checkout_sessions.create(
    amount_cents=5000,
    currency="usd",
    success_url="https://mysite.com/thanks",
    cancel_url="https://mysite.com/cancel",
)
print(session["checkout_url"])  # Redirect your customer here

Configuration

client = satsrail.SatsRail(
    "sk_live_...",
    base_url="https://app.satsrail.com/api/v1",  # default
    timeout=30,  # seconds, default
)

Option	Type	Default	Description
base_url	str	https://app.satsrail.com/api/v1	API base URL
timeout	int	30	Request timeout in seconds

Test Mode

Use test mode keys (sk_test_...) to create isolated test data:

client = satsrail.SatsRail("sk_test_...")

API Reference

Checkout Sessions

Create hosted checkout pages where customers complete payment.

session = client.checkout_sessions.create(
    amount_cents=5000,       # required — $50.00
    currency="usd",          # optional
    success_url="https://mysite.com/thanks",
    cancel_url="https://mysite.com/cancel",
)
# session["checkout_url"] — redirect customer here
# session["id"], session["token"], session["expires_at"]

Orders

Create and manage payment orders.

# Create
order = client.orders.create(
    total_amount_cents=5000,
    currency="usd",
    items=[{"name": "Widget", "price_cents": 5000, "qty": 1}],
    metadata={"order_ref": "PO-12345"},
    # generate_invoice=True,       — auto-generate invoice
    # payment_method="lightning",
)

# List (paginated)
orders = client.orders.list(status="pending", page=1, per_page=25)
# orders["data"] — list of order objects
# orders["meta"] — {"current_page", "total_pages", "total_count", ...}

# Retrieve (with optional expansion)
order = client.orders.retrieve("order_id", expand="invoice,payment")

# Update
updated = client.orders.update("order_id", metadata={"note": "updated"})

# Cancel
client.orders.delete("order_id")

Invoices

Generate and track invoices for orders.

# Generate an invoice for an order
invoice = client.invoices.generate(
    order_id="order_id",
    payment_method="lightning",  # "lightning" | "onchain" | "usdt"
)

# Retrieve
inv = client.invoices.retrieve("invoice_id")

# Check status
status = client.invoices.status("invoice_id")

# Get QR code
qr = client.invoices.qr("invoice_id")

Payments (read-only)

View payment records.

# List (paginated, with date filters)
payments = client.payments.list(
    page=1,
    per_page=25,
    start_date="2026-01-01",
    end_date="2026-01-31",
)

# Retrieve
payment = client.payments.retrieve("payment_id")

Payment Requests

Unified API for Lightning/Bitcoin/USDT payments.

# Create
pr = client.payment_requests.create(
    amount_cents=1000,
    payment_method="lightning",
)

# Retrieve
pr = client.payment_requests.retrieve("pr_id")

# Check status
status = client.payment_requests.status("pr_id")

Wallets (read-only)

View merchant wallets.

wallets = client.wallets.list()
wallet = client.wallets.retrieve("wallet_id")

Webhooks

Manage webhook endpoints for real-time event notifications.

# Create (returns secret_key — save it!)
wh = client.webhooks.create(
    url="https://mysite.com/webhooks",
    events=["order.created", "invoice.paid", "payment.received"],
    description="Production endpoint",
)
print(wh["secret_key"])  # whsec_... — only shown once

# List (includes available_events)
webhooks = client.webhooks.list()

# Retrieve
wh = client.webhooks.retrieve("webhook_id")

# Update
client.webhooks.update("webhook_id", url="https://mysite.com/webhooks/v2", active=False)

# Delete
client.webhooks.delete("webhook_id")

Merchant

Access authenticated merchant data.

# Get merchant profile
me = client.merchant.retrieve()

# List merchant orders
orders = client.merchant.list_orders(page=1)

# List merchant payments
payments = client.merchant.list_payments(page=1)

Error Handling

All errors extend SatsRailError and include structured details:

from satsrail import (
    SatsRailError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
)

try:
    client.orders.create(total_amount_cents=-1, items=[])
except ValidationError as e:
    print(e.status)      # 422
    print(e.code)        # "validation_error"
    print(e.message)     # "Validation failed"
    print(e.details)     # ["Total amount cents must be greater than 0"]
    print(e.request_id)  # "req_..."
except AuthenticationError:
    pass  # 401 — bad API key
except NotFoundError:
    pass  # 404 — resource doesn't exist
except RateLimitError:
    pass  # 429 — slow down
except SatsRailError:
    pass  # Other API error

Error Class	Status	When
AuthenticationError	401	Invalid or missing API key
NotFoundError	404	Resource not found
ValidationError	422	Invalid request parameters
RateLimitError	429	Too many requests
SatsRailError	*	All other API errors

License

MIT — see LICENSE.