Configure Fluent
Keep the SDK client open for your application or worker lifespan. Fluent reuses it; the caller remains responsible for closing it. See installation.
Add your storage driver
The driver below is your implementation of the storage contracts.
Use one scope per tenant, storefront and test/live mode. Django users can use
vatly-django instead of implementing this adapter.
from vatly import AsyncVatlyClient
from vatly_fluent import Vatly, Wiring
def example(api: AsyncVatlyClient, driver):
return Vatly(
Wiring(
api=api,
redirect_url_success="https://app.example.com/billing/success",
redirect_url_canceled="https://app.example.com/billing/canceled",
webhook_secret="replace-with-your-endpoint-secret",
checkouts=driver.checkouts,
bindings=driver.bindings,
orders=driver.orders,
subscriptions=driver.subscriptions,
refunds=driver.refunds,
chargebacks=driver.chargebacks,
webhook_calls=driver,
events=driver,
)
)
Load the endpoint secret from your secret manager rather than a source-code literal. The sample value is only a placeholder.
| Wiring field | Required for |
|---|---|
api, both redirect URLs | Hosted checkout creation |
checkouts | .for_entity(...) and resource ownership links |
bindings | Customer-to-host identity mapping |
orders, subscriptions | Local signed snapshots and lifecycle helpers |
refunds, chargebacks | Optional local reversal records |
webhook_secret, webhook_calls, events | Verified, transactional delivery and outbox |
Missing wiring fails when its feature is used. API-only checkout creation does not require repositories. A customer email in a profile does not create a remote customer.
Retry the same business operation
from vatly import RequestOptions
from vatly_fluent import Vatly
async def example(vatly: Vatly):
return (
await vatly.checkout_builder()
.with_items(
[
{"id": "one_off_product_example", "quantity": 1},
]
)
.create(options=RequestOptions(idempotency_key="purchase:42", timeout=10))
)
Persist that key before calling. Reuse it after a network or local-save failure;
do not generate a second purchase key on retry. SDK errors propagate unchanged.
Live/test keys share a host; .in_testmode() checks the key, not switches it.