​
Sessions

Everything is a Session. Every payment, deposit, and transfer is a Session object. The session ID (ses_xxx) is the universal reference — it’s the payment intent, the checkout URL, and the status tracker all in one.

​
Session Types

TypeCreated byWhat it is
checkoutDeveloper or widgetAny payment — online, POS, API paywall
transferDeveloperWallet-to-wallet (routed via Stableyard for privacy)
depositSystem (auto)Created when money arrives at a deposit address
checkout is the default. You don’t need to specify it.

​
Payment Flows

​
One-Step Flow (agents, server-to-server)

If you know the source chain upfront, pass sourceChain during session creation: 
POST /v2/sessions {
  amount: 2000000,
  destination: "shop@stableyard",
  sourceChain: "polygon"        ← enables one-step flow
}
→ Returns session + deposit address + gateway calldata (all in one response)
→ Send funds to deposit.address
→ POST /sessions/:id/submit-tx { txHash, chain }
→ Webhook: payment.settled
One API call to get everything needed to pay.

​
Two-Step Flow (widgets, UIs with chain selection)

If you want the user to pick their source chain: 
POST /v2/sessions { amount: 2000000, destination: "shop@stableyard" }
→ Returns session: { id, status: "open", amount, checkoutUrl, fees, expiresAt }
→ No deposit address yet — session is just a payment intent

User picks "polygon"
→ POST /sessions/:id/quote { sourceChain: "polygon", commit: true }
→ Returns deposit address + route + alternatives

​
Execution Modes

ModeBehaviorWhen to use
standard (default)Full meta-aggregation, gateway calldata (approve + deposit, 2 tx)API integrations
boostedReturns deposit address, 1 txWidget, agents — simpler UX

​
Quote → Commit Flow

  • Quote without commit = preview with alternatives. User can switch chains freely. No order created.
  • Quote with commit: true = creates routing order, returns deposit info.
  • alternatives always returned — all providers ranked by output amount.

​
Key Points

  • Same-chain: direct transfer to merchant, sub-second, no routing
  • Cross-chain: 3–15 seconds via Stableyard’s routing network
  • Vault payment: separate flow via POST /sessions/:id/pay with EIP-712 signature
  • Privacy: Transfers route through Stableyard — Alice → Stableyard → Bob (separate transactions, no direct link)