POST
/
sessions
curl -X POST https://api.stableyard.fi/v2/sessions \
  -H "Authorization: Bearer sy_secret_*" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  -d '{
    "type": "checkout",
    "amount": 5000000,
    "currency": "USDC",
    "destination": "acc_merchant",
    "description": "Order #123",
    "sourceChain": "base",
    "sourceToken": "USDC",
    "executionMode": "boosted"
  }'

{
  "object": "session",
  "id": "ses_abc123",
  "type": "checkout",
  "status": "open",
  "amount": 5000000,
  "amountFormatted": "5.00",
  "currency": "USDC",
  "description": "Order #123",
  "destination": {
    "accountId": "acc_merchant",
    "paymentAddress": "merchant@stableyard",
    "wallet": "0x...",
    "chain": "polygon",
    "token": "USDC"
  },
  "paymentMethods": [
    {
      "type": "crypto",
      "depositAddress": "0x...",
      "chain": "base",
      "chainId": 8453,
      "tokens": ["USDC"]
    }
  ],
  "fees": {
    "total": 25000,
    "totalFormatted": "0.025",
    "stableyard": 15000,
    "partner": 10000
  },
  "route": {
    "sourceChain": "base",
    "destChain": "polygon",
    "estimatedSeconds": 30
  },
  "qr": {
    "universal": "https://pay.stableyard.fi/ses_abc123"
  },
  "expiresAt": 1710675000,
  "livemode": false,
  "createdAt": "2026-03-18T10:20:30.000Z",
  "requestId": "req_abc123"
}
Create a new payment session. Supports idempotency via Idempotency-Key header. Auth: sy_secret_* | sy_pub_*
​
type
string
Session type. Default: checkout. One of: checkout, deposit, transfer
​
amount
number
required
Payment amount in smallest unit (e.g., 1000000 = 1 USDC). Minimum: 100000
​
currency
string
Token currency. Default: USDC. One of: USDC, USDT
​
destination
string
required
Destination account — account ID, wallet address, or payment address
​
description
string
Human-readable description of the payment
​
metadata
object
Arbitrary key-value metadata attached to the session
​
successUrl
string
URL to redirect after successful payment
​
cancelUrl
string
URL to redirect if payment is cancelled
​
expiresIn
number
Session expiry in seconds from creation
​
acceptedChains
array
List of accepted chain names (e.g., ["base", "polygon"])
​
qrFormats
array
QR code formats to generate (e.g., ["universal", "solana", "evm"])
​
sourceChain
string
Expected source chain name for routing
​
sourceToken
string
Expected source token
​
executionMode
string
Routing mode. Default: standard. One of: standard, boosted
​
slippageBps
number
Slippage tolerance in basis points. Default: 50
​
splits
array
Payment split configuration
​
resource
string
Resource URL for x402 payments
curl -X POST https://api.stableyard.fi/v2/sessions \
  -H "Authorization: Bearer sy_secret_*" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  -d '{
    "type": "checkout",
    "amount": 5000000,
    "currency": "USDC",
    "destination": "acc_merchant",
    "description": "Order #123",
    "sourceChain": "base",
    "sourceToken": "USDC",
    "executionMode": "boosted"
  }'

{
  "object": "session",
  "id": "ses_abc123",
  "type": "checkout",
  "status": "open",
  "amount": 5000000,
  "amountFormatted": "5.00",
  "currency": "USDC",
  "description": "Order #123",
  "destination": {
    "accountId": "acc_merchant",
    "paymentAddress": "merchant@stableyard",
    "wallet": "0x...",
    "chain": "polygon",
    "token": "USDC"
  },
  "paymentMethods": [
    {
      "type": "crypto",
      "depositAddress": "0x...",
      "chain": "base",
      "chainId": 8453,
      "tokens": ["USDC"]
    }
  ],
  "fees": {
    "total": 25000,
    "totalFormatted": "0.025",
    "stableyard": 15000,
    "partner": 10000
  },
  "route": {
    "sourceChain": "base",
    "destChain": "polygon",
    "estimatedSeconds": 30
  },
  "qr": {
    "universal": "https://pay.stableyard.fi/ses_abc123"
  },
  "expiresAt": 1710675000,
  "livemode": false,
  "createdAt": "2026-03-18T10:20:30.000Z",
  "requestId": "req_abc123"
}