​
Session Lifecycle

Every session follows the same lifecycle, regardless of type. 
                    ┌─────────┐
                    │  open   │ ← session created, waiting for payment
                    └────┬────┘
                         │
              payment detected / tx submitted
                         │
                    ┌────▼────┐
                    │ pending │ ← payment seen, verifying
                    └────┬────┘
                         │
              cross-chain? Stableyard routing
                         │
                    ┌────▼────┐
                    │ routing │ ← cross-chain routing (3-15s)
                    └────┬────┘
                         │
              funds delivered to merchant
                         │
                    ┌────▼────┐
                    │ settled │ ← done, merchant received funds
                    └─────────┘

  Other terminal states:
  ├── expired  (TTL elapsed, no payment)
  ├── failed   (routing failed, auto-refund started)
  └── refunded (merchant initiated refund)

​
Status Descriptions

StatusDescriptionNext States
openCreated, waiting for paymentpending, expired
pendingPayment detected, confirming on-chainrouting, settled, failed
routingCross-chain routingsettled, failed
settledComplete — funds received by merchantrefunded
expiredSession timed out with no payment(terminal)
failedRouting failed, auto-refund initiated(terminal)
refundedMerchant-initiated refund(terminal)

​
Same-Chain vs Cross-Chain

  • Same-chain: open → pending → settled (sub-second)
  • Cross-chain: open → pending → routing → settled (3–15 seconds)

​
Webhook Events

TransitionWebhook Event
→ pendingpayment.pending
→ routingpayment.routing
→ settledpayment.settled
→ failedpayment.failed
→ expiredsession.expired
Refund initiatedrefund.created
Refund completedrefund.settled

​
Refunds

  • POST /v2/sessions/:id/refund with amount and reason
  • Partial refunds allowed (multiple times)
  • Total refunded cannot exceed original amount
  • Auto-refund on payment failure (Stableyard handles this)
Stableyard is a facilitator, not an arbitrator. We route money back — the decision to refund is yours.