Core concepts.
Everything OpenSettle does sits on top of four primitives. Once you have a mental model of each, the rest of the product is predictable.
Non-custodial settlement
OpenSettle never takes possession of customer or merchant funds. Customers send payments directly to your wallet — we observe them on-chain.
Off-chain billing
Our fee is accrued per confirmed payment and billed in a single monthly invoice. No router contract, no on-chain split, no extra gas.
Chain-agnostic routing
Hosted checkout is live on Base, Ethereum, Polygon, and Arbitrum; payment detection also covers Solana and Tron. Chain becomes a property on a payment, not a migration.
Signed events
State changes emit signed webhooks within a second of on-chain finality. Idempotent, retried, and replayable.
Settlement model
Customers transfer the full amount directly to your settlement wallet — we never sit between them and you on-chain. Our chain-reader workers observe the deposit, match it to the payment intent, and emit a confirmed event.
We accrue our share of each confirmed payment off-chain and aggregate it into a single monthly invoice. You pay it in any supported stablecoin. This keeps gas costs minimal and avoids the contract risk of an on-chain splitter, which we plan to introduce as an opt-in once volume justifies the audit overhead.
Idempotency
Every POST request accepts an Idempotency-Key header. We cache the response for 24 hours. Retrying a request with the same key returns the original response without re-executing. This is the safe way to handle retries from your server or a webhook handler.
Environments
- Test mode — an isolated test workspace with
sk_test_/pk_test_keys and its own data, fully separate from your live workspace. Identical API shape as live. To drive a confirm→settle→webhook loop without real funds, callPOST /v1/workspaces/{workspaceId}/checkouts/{id}/simulate_payment(SDK:os.checkouts.simulatePayment(checkoutId)); it synthesizes a confirmed payment and fires the realpayment.confirmedwebhook. A real (non-simulated) confirmation still requires a real on-chain transfer. - Live mode— real money, real chain. Toggle in the dashboard when you're ready. You can flip back and forth at any time.