Build on Subsie
Subsie is API-first stablecoin payment infrastructure on Base. You create checkout sessions over REST, buyers pay USDC from their own wallets on a hosted page, settlement happens on-chain in a single non-custodial transaction, and you get signed webhooks plus retrieval APIs to confirm everything server-side.
Quickstart
Test key to settled USDC payment, end to end.
API reference
Every endpoint, object, and error in the v1 REST API.
Webhooks
Signed events, verification, retries, and observability.
SDKs
@orven/node — the publish-ready server-side TypeScript client.
How a payment works
The whole integration is one loop. Your server creates a checkout session with the terms of the charge; Subsie returns a hosted URL; the buyer connects a wallet and pays; the PaymentRouter contract settles the transfer on-chain in production; Subsie verifies the settlement and notifies you. Test mode uses the same checkout/session model on Base Sepolia, with a temporary direct-transfer fallback until the Sepolia router is configured.
| Step | What happens |
|---|---|
| 1. Create | POST /api/v1/checkout/sessions with a title, amount, and your internal reference. The response includes a hosted url. |
| 2. Redirect | Send the buyer to the session URL. Subsie hosts the checkout page: wallet connect, USDC approval, and payment. |
| 3. Settle | The buyer pays through the PaymentRouter contract when it is configured. Funds move directly from the buyer to your verified settlement wallet (and the fee split to Subsie) in one transaction. Subsie never holds funds. |
| 4. Confirm | Subsie verifies the on-chain settlement against the session, marks it completed, and sends checkout.session.completed and payment.succeeded webhooks. You can always re-check with the retrieval APIs. |
Authentication
Every API request is authenticated with a secret key in the Authorization header. Create keys on the Developers page of your dashboard. Keys are shown once and stored hashed.
curl https://pay.example.com/api/v1/payments \
-H "Authorization: Bearer orven_sk_test_..."The base URL is the host where your Subsie instance runs — the same origin that serves the dashboard. All endpoints in these docs are relative to it.
Test and live mode
Keys come in two modes, and the mode decides everything: which chain sessions settle on, which data you can see, and which webhooks fire. Test and live data never mix.
| Test mode | Live mode | |
|---|---|---|
| Key prefix | orven_sk_test_ | orven_sk_live_ |
| Network | Base Sepolia (chain 84532) | Base (chain 8453) |
| USDC | 0x036CbD53842c5426634e7929541eC2318f3dCF7e | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Money | Faucet USDC, free to test | Real funds |
| Subscriptions | Not available (returns 400) | Available |
Every API object carries a livemode boolean so your handlers can assert they are processing the data they expect.
Core objects
| Object | Prefix | What it is |
|---|---|---|
| Checkout session | cs_ | One intent to charge: terms, hosted URL, expiry, and a snapshot of the fee terms at creation. |
| Payment | pay_ | A settled on-chain charge with gross, fee, and net amounts plus the transaction hash. |
| Subscription | sub_ | A recurring on-chain billing agreement, charged by Subsie on schedule (live mode). |
| Payment attempt | att_ | One recurring charge try, including failures and the dunning retry state. |
| Settlement wallet | wlt_ | A merchant wallet that proved ownership by signing a message. Payments settle only to verified wallets. |
| Webhook endpoint | we_ | A URL that receives signed event deliveries for one mode. |