sapliyio-fintech

Official Python SDK for the Sapliy Fintech Ecosystem. Build financial applications with a clean, Pythonic API.

Features

• Payments — Create charges, handle refunds, manage payment lifecycle
• Wallets — User balances and internal accounting
• Ledger — Double-entry bookkeeping for high-integrity transactions
• Billing — Subscriptions and recurring billing
• Connect — Multi-tenant support and managed accounts
• Webhooks — Event handling with signature verification
• Type Hints — Full typing support for IDE autocomplete

Installation

pip install sapliyio-fintech

Quick Start

fromsapliyio_fintechimportFintechClientclient=FintechClient(api_key="sk_test_...")
# Create a paymentpayment=client.payments.create(
amount=2000, # $20.00currency="USD",
source_id="src_123",
description="Order #1234"
)
print(f"Payment created: {payment.id}")

Configuration

# Custom base URL (for self-hosted)client=FintechClient(
api_key="sk_test_...",
base_url="https://api.yourdomain.com"
)
# Custom timeoutclient=FintechClient(
api_key="sk_test_...",
timeout=30# seconds
)

API Reference

Payments

# Create a chargepayment=client.payments.create(
amount=1000,
currency="USD",
source_id="src_123",
description="Coffee"
)
# Get payment detailspayment=client.payments.get("pay_123")
# Refund a paymentpayment=client.payments.refund("pay_123", amount=500) # partial refund

Wallets

# Create a walletwallet=client.wallets.create(
name="User Wallet",
currency="USD"
)
# Get wallet balancewallet=client.wallets.get("wal_123")
# Credit (add funds)wallet=client.wallets.credit(
wallet_id="wal_123",
amount=1000,
description="Deposit"
)
# Debit (withdraw funds)wallet=client.wallets.debit(
wallet_id="wal_123",
amount=500,
description="Purchase"
)

Ledger

# Record a transactionresponse=client.ledger.record_transaction(
account_id="acc_123",
amount=1000,
currency="USD",
description="Payment received",
reference_id="ref_456"
)
# Get account detailsaccount=client.ledger.get_account("acc_123")
print(f"Balance: {account.balance}")

Billing

# Create a subscriptionsubscription=client.billing.create_subscription(
customer_id="cust_123",
plan_id="plan_monthly"
)
# Get subscriptionsubscription=client.billing.get_subscription("sub_123")
# Cancel subscriptionclient.billing.cancel_subscription("sub_123")

Events (Automation)

# Emit an event to trigger flowsclient.events.emit("checkout.completed", {
"cartId": "cart_123",
"total": 5000,
"customerId": "cust_456"
})

Flow Builder Template Variables

When creating flows in the Sapliy Flow Builder, you can use Handlebars template syntax to dynamically reference event data in your automation logic. This is particularly useful for approval messages, webhook payloads, and conditional logic.

Available Variables

Variable	Description	Example
{{event.type}}	The event type that triggered the flow	payment.completed
{{event.id}}	Unique event identifier	evt_abc123
{{event.payload.*}}	Access any field from the event payload	{{event.payload.amount}}
{{event.createdAt}}	Timestamp when event was created	2024-01-15T10:30:00Z

Usage Examples

Approval Node Message

Approval required for payment of ${{event.payload.amount}}{{event.payload.currency}}
Customer: {{event.payload.customerId}}

When you emit an event like:

client.events.emit("payment.high_value", {
"amount": 10000,
"currency": "USD",
"customerId": "cust_456"
})

The approval message will render as:

Approval required for payment of $10000 USD
Customer: cust_456

Webhook Payload Template

{
"orderId": "{{event.payload.orderId}}",
"status": "approved",
"approvedAt": "{{event.createdAt}}",
"amount": {{event.payload.amount}}
}

Best Practices

1. Always validate data exists: Use the Flow Builder's test mode to ensure your template variables resolve correctly
2. Type safety: Numeric fields don't need quotes in JSON templates: {{amount}} not "{{amount}}"
3. Nested objects: Access nested data with dot notation: {{event.payload.customer.email}}
4. Debugging: Use sapliy listen to see the actual event payloads and verify your template paths

Webhook Handling

Flask Example

fromflaskimportFlask, requestfromsapliyio_fintechimportFintechClientapp=Flask(__name__)
client=FintechClient(api_key="sk_test_...")
@app.route("/webhooks", methods=["POST"])defwebhook():
payload=request.datasignature=request.headers.get("X-Sapliy-Signature")
secret="whsec_..."try:
event=client.webhooks.construct_event(payload, signature, secret)
exceptValueError:
return"Invalid signature", 400ifevent.type=="payment.succeeded":
payment=event.data.object# Handle successful paymentelifevent.type=="payment.failed":
# Handle failed paymentpassreturn {"received": True}

Django Example

fromdjango.httpimportJsonResponsefromdjango.views.decorators.csrfimportcsrf_exemptfromsapliyio_fintechimportFintechClientclient=FintechClient(api_key="sk_test_...")
@csrf_exemptdefwebhook_view(request):
payload=request.bodysignature=request.headers.get("X-Sapliy-Signature")
secret="whsec_..."try:
event=client.webhooks.construct_event(payload, signature, secret)
exceptValueError:
returnJsonResponse({"error": "Invalid signature"}, status=400)
# Handle eventreturnJsonResponse({"received": True})

Async Support

importasynciofromsapliyio_fintechimportAsyncFintechClientasyncdefmain():
client=AsyncFintechClient(api_key="sk_test_...")
payment=awaitclient.payments.create(
amount=2000,
currency="USD",
source_id="src_123",
description="Async payment"
)
print(f"Payment: {payment.id}")
asyncio.run(main())

Error Handling

fromsapliyio_fintech.exceptionsimportFintechError, PaymentErrortry:
payment=client.payments.get("invalid_id")
exceptPaymentErrorase:
print(f"Payment error: {e.message}")
exceptFintechErrorase:
print(f"API error ({e.status_code}): {e.message}")

Part of Sapliy Fintech Ecosystem

• fintech-ecosystem — Core backend
• fintech-sdk-node — Node.js SDK
• fintech-sdk-go — Go SDK

License

MIT © Sapliy