​
Quickstart

This guide walks you through creating your first payment session with Stableyard.

​
Prerequisites

  • A Stableyard account with your public key (sy_pub_* or sy_test_pub_*)
  • A destination — your payment address (e.g., shop@stableyard) or wallet address

​
1. Create a Payment Session

curl -X POST https://api.stableyard.fi/v2/sessions \
  -H "Authorization: Bearer sy_test_pub_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-payment-001" \
  -d '{
    "amount": 1000000,
    "currency": "USDC",
    "destination": "acc_your_account_id",
    "description": "Test payment",
    "sourceChain": "base",
    "sourceToken": "USDC"
  }'
The response includes a session with deposit info (because sourceChain was provided): 
{
  "object": "session",
  "id": "ses_abc123",
  "status": "open",
  "amount": 1000000,
  "currency": "USDC",
  "checkoutUrl": "https://pay.stableyard.fi/ses_abc123",
  "deposit": {
    "address": "0x...",
    "methods": [{ "type": "deposit_address", "address": "0x..." }]
  },
  "fees": {
    "total": 2500,
    "totalFormatted": "0.003"
  },
  "expiresAt": 1710672300
}

​
2. Listen for Payment Events

Register a webhook to get notified when payments are completed: 
curl -X POST https://api.stableyard.fi/v2/webhooks \
  -H "Authorization: Bearer sy_test_pub_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/stableyard",
    "events": ["payment.settled", "payment.failed"]
  }'

​
3. Handle the Webhook

When a payment settles, you’ll receive a payment.settled event: 
{
  "id": "evt_xyz789",
  "object": "event",
  "type": "payment.settled",
  "created": 1710671400,
  "livemode": false,
  "data": {
    "sessionId": "ses_abc123",
    "status": "settled",
    "amount": 1000000,
    "currency": "USDC",
    "settledAt": 1710671400
  }
}
Verify the webhook signature using your webhook secret, then credit the user’s balance in your system.

​
Next Steps

Deposit Addresses

Set up reusable deposit addresses for users

Vault Management

Deploy a Gnosis Safe vault for settlement

x402 Payments

Monetize APIs with pay-per-call

Full API Reference

Explore every endpoint