███████╗ █████╗ ██████╗ ██╗ ██╗ ██╗ ██╗ ██╗
██╔════╝██╔══██╗██╔══██╗██║ ██║ ██║ ╚██╗ ██╔╝
███████╗███████║██████╔╝██║ ██║ ██║ ╚████╔╝
╚════██║██╔══██║██╔══██╗██║ ██║ ██║ ╚██╔╝
███████║██║ ██║██║ ██║███████╗╚██████╔╝ ██║
╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝
Official Python SDK for the Sapliy AI-Native Financial Operations Platform.
Sapliy is an AI-native Financial Operations Intelligence Layer that turns business goals into reliable, explainable, auditable financial outcomes — by orchestrating the systems companies already run (Stripe, PayPal, Paddle, HubSpot, Xero), not replacing them.
| Badge | |
|---|---|
| Package | sapliyio-fintech |
| Version | 1.0.0 |
| License |  |
| PyPI |  |
| Python | >=3.7 (pydantic v2 models) |
Legacy package name:
sapliyio-fintech(importsapliyio_fintech) is the published name, kept for compatibility with the platform's fintech heritage. It is the official Sapliy Python SDK.
The official Python client for the Sapliy core backend (sapliy-ecosystem). A generated OpenAPI client (SapliyClient) with pydantic v2 models covering auth, billing, events, executions, flows, ledger, payments, wallets, and zones — plus a first-class Operational Playbook catalog that maps business goals to the MVP playbooks.
Like every Sapliy SDK, it orchestrates and audits the systems you already run — it never replaces your payment stack.
- Payments — create, fetch, and confirm payment intents
- Wallets — read balances, top up, and transfer funds
- Ledger — double-entry bookkeeping: accounts and transactions
- Billing — subscriptions and recurring billing
- Zones — test/live environment isolation
- Events — emit, replay, and list past events (drives the MVP Operational Playbooks)
- Flows & Executions — manage automation flows and resume paused executions
- Playbooks —
.playbooks.list()/.playbooks.bootstrap()for the MVP catalog - Convenience helpers —
client.emit_event()andclient.record_transaction()wrap common calls - Type hints — full typing support for IDE autocomplete;
py.typedmarker included - Fixed-point money — all amounts are integer cents, never floats
pip install sapliyio-fintechfrom sapliyio_fintech import SapliyClient, CreatePaymentIntentRequest
client = SapliyClient(api_key="sk_test_...")
# Create a payment intent (amount in cents)
payment = client.payments.create_payment_intent(
x_zone_id="zone_main_123",
create_payment_intent_request=CreatePaymentIntentRequest(
amount=2000, # $20.00
currency="USD",
description="Order #1234"
)
)
print(f"Payment created: {payment.id}")
# List the MVP Operational Playbook catalog
for playbook in client.playbooks.list():
print(f"- {playbook['type']}: {playbook['description']}")
# Bootstrap a scaffold config for a playbook
print(client.playbooks.bootstrap("revenue-recovery"))The constructor defaults to
https://api.sapliy.io.
# Custom base URL (for self-hosted)
client = SapliyClient(
api_key="sk_test_...",
base_url="https://api.yourdomain.com"
)payment = client.payments.create_payment_intent(
x_zone_id="zone_main_123",
create_payment_intent_request=CreatePaymentIntentRequest(
amount=1000,
currency="USD",
description="Coffee"
)
)
payment = client.payments.get_payment_intent(id="pi_123", x_zone_id="zone_main_123")
client.payments.confirm_payment_intent(
id=payment.id,
x_zone_id="zone_main_123",
confirm_payment_intent_request=ConfirmPaymentIntentRequest(payment_method_id="pm_card_visa")
)wallet = client.wallets.get_wallet(user_id="user_123", x_zone_id="zone_main_123")
print(f"Balance: {wallet.balance} {wallet.currency}")
client.wallets.topup_wallet(
x_zone_id="zone_main_123",
topup_wallet_request=TopupWalletRequest(
amount=1000,
currency="USD",
reference_id="topup_001"
)
)
client.wallets.transfer_wallet(
x_zone_id="zone_main_123",
transfer_wallet_request=TransferWalletRequest(
to_user_id="user_456",
amount=500,
currency="USD",
reference_id="transfer_001"
)
)client.ledger.v1_ledger_accounts_post(
x_zone_id="zone_main_123",
v1_ledger_accounts_post_request=V1LedgerAccountsPostRequest(
name="Merchant",
type="liability",
currency="USD"
)
)
# Record a double-entry transaction
client.ledger.v1_ledger_transactions_post(
x_zone_id="zone_main_123",
v1_ledger_transactions_post_request=V1LedgerTransactionsPostRequest(
reference_id="ref_456",
description="Payment received",
entries=[...]
)
)
account = client.ledger.get_ledger_account(id="acc_123", x_zone_id="zone_main_123")
txn = client.ledger.get_ledger_transaction(id="txn_123", x_zone_id="zone_main_123")subscription = client.billing.create_subscription(
create_subscription_request=CreateSubscriptionRequest(
plan_id="plan_monthly",
customer_id="cust_123"
)
)
subscription = client.billing.get_subscription(id="sub_123")
client.billing.cancel_subscription(id="sub_123")event = client.events.emit_event(EmitEventRequest(
type="payment.failed",
data={"amount": 2000, "currency": "USD"},
idempotency_key="idem-1"
))
events = client.events.get_past_events(zone_id="zone_main_123", limit=20, offset=0)
client.events.replay_event(
event_id="evt_123",
replay_event_request=ReplayEventRequest(zone_id="zone_main_123")
)client.zones.create_zone(create_zone_request=CreateZoneRequest(
org_id="org_123",
name="My Zone",
mode="test"
))
zones = client.zones.list_zones(org_id="org_123")client.playbooks.list() # list of catalog dicts
client.playbooks.bootstrap("refund-approval") # scaffold config dict# Wraps events.emit_event
client.emit_event(EmitEventRequest(type="checkout.completed", data={"total": 5000}))
# Wraps ledger.v1_ledger_transactions_post
client.record_transaction("zone_main_123", V1LedgerTransactionsPostRequest(...))The SDK ships the same MVP playbook catalog the backend playbook engine and the console expose:
| Playbook | Type | Purpose |
|---|---|---|
| Revenue Recovery & Dunning | revenue-recovery |
Recover failed subscription payments with automated dunning and smart retries |
| Refund & Invoice Orchestration | refund-approval |
Route refunds and invoice adjustments through the policy engine for approval |
| Invoice Reminders | invoice-reminders |
Send automated reminders for overdue invoices |
flowchart LR
App[Your Python service] --> SDK[SapliyClient<br/>sapliyio_fintech]
SDK --> Gateway[Sapliy API Gateway<br/>sapliy-ecosystem]
Gateway --> Engine[Playbook & Policy Engines]
Engine --> Stripe[Stripe / PayPal / Paddle]
Engine --> HubSpot[HubSpot / Xero]
Engine --> Log[Audit Decision Log]
The SDK never talks to providers directly — it drives the Sapliy gateway, which orchestrates the systems you already run and records every decision in the immutable audit log.
The generated client surfaces ApiException (from sapliyio_fintech.exceptions) on API errors:
from sapliyio_fintech.exceptions import ApiException
try:
payment = client.payments.get_payment_intent(id="invalid_id", x_zone_id="zone_main_123")
except ApiException as e:
print(f"API error ({e.status}): {e.reason}")python3 -m unittest discover -s tests # run the test suiteSee the examples/ directory for financial-audit and real-world usage walkthroughs.
sapliy-ecosystem— core backend, playbook engine, policy & audit enginessapliy-sdk-node— Node.js SDK (@sapliyio/fintech)sapliy-sdk-go— Go SDKsapliy-examples— sample apps per language- Docs — docs.sapliy.io
MIT © Sapliy