Session Payment

Session Payment is the primary way to accept payments through Stablecoin Harness. Each payment is a session — a short-lived object with a unique deposit address, an amount, an expiry, and a settlement destination.

How it works

Customer wallet ──► Deposit address ──► Auto-swap to sUSDe ──► Merchant settlement
                       (CREATE2)              (on receive)            (forward)

1. Your server creates a session.
2. We return a deterministic deposit address (CREATE2-derived) and a hosted redirect URL.
3. The customer sends any supported stablecoin to that address.
4. On confirmation, funds are swapped to sUSDe (or your configured settlement asset) and forwarded to your merchant wallet.
5. We send a signed webhook and redirect the customer to your successUrl.

Create a session

curl -X POST https://api.stablecoinx.com/v1/sessions \
  -H "Authorization: Bearer $STABLECOINX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.99",
    "currency": "USD",
    "chain": "base",
    "successUrl": "https://example.com/orders/1234/complete",
    "metadata": { "order_id": "1234" }
  }'

Response:

{
  "id": "sess_01HX2K3...",
  "depositAddress": "0xa1b2c3...",
  "amount": "49.99",
  "currency": "USD",
  "chain": "base",
  "acceptedAssets": ["USDC", "USDT", "DAI", "USDe"],
  "status": "awaiting_payment",
  "successUrl": "https://example.com/orders/1234/complete",
  "expiresAt": "2026-05-26T17:30:00Z",
  "createdAt": "2026-05-26T17:00:00Z"
}

Session lifecycle

Status	Meaning
awaiting_payment	Session is open. Deposit address is live.
detected	Funds detected on-chain; waiting for confirmation.
swapping	Funds confirmed; swap to settlement asset in flight.
completed	Funds settled to merchant wallet. Terminal.
expired	Session expired before funds arrived. Terminal.
failed	Settlement could not complete. Terminal. Includes failureReason.

Webhooks

Subscribe to session.detected, session.completed, session.expired, and session.failed. Each delivery is signed with HMAC-SHA256 in the X-StablecoinX-Signature header — see Quickstart for verification.

Sample payload:

{
  "event": "session.completed",
  "id": "evt_01HX2K9...",
  "createdAt": "2026-05-26T17:05:23Z",
  "data": {
    "session": {
      "id": "sess_01HX2K3...",
      "amount": "49.99",
      "currency": "USD",
      "settledAsset": "sUSDe",
      "settledAmount": "49.97",
      "settlementTx": "0xdeadbeef...",
      "metadata": { "order_id": "1234" }
    }
  }
}

Address computation

Deposit addresses are deterministic. Compute them client-side to display the address before calling the API — useful for low-latency checkout UIs:

import { computeSessionAddress } from "@stablecoinx/sdk";

const address = computeSessionAddress({
  merchantId: "mrch_...",
  sessionId: "sess_01HX2K3...",
  chain: "base",
});

Supported chains

Chain	Status	Settlement asset
Base	GA	sUSDe
Arbitrum	GA	sUSDe
Optimism	GA	sUSDe
Ethereum	GA	sUSDe
Base Sepolia	Sandbox	test-sUSDe

Idempotency

Pass an Idempotency-Key header on POST /v1/sessions to retry safely. Duplicate requests within 24 hours return the original session.

Related

Paymaster

Sponsor or accept gas in stablecoins for the customer’s transaction. Read →

Treasury Dashboard

Operate the funds that settle from sessions. Read →