Session (Core)

A Swapped Connect session is one payment run identified by sessionId. Load it once, run Wallets, Exchange Pay, Cash App, or Coinbase while it is active, then call restartSession() before another payment.

For UI, prefer client.getSessionView() (and the sessionView:changed event) over reading raw getSession()?.session.status. The view classifies API status, maintenance, and runtime rejection into screens you can switch on.

getSession() / loadSession() return SessionData. The API session is the nested session field — status is session.session.status, not session.status.

Do not read session.transactionHash — the public session model omits it; use transactionData or a flow summary instead.

Status vs view

Layer	Type	Use for
API status	SessionStatus on getSession()?.session.status	Debugging / logging
UI view	SessionView from getSessionView / client.getSessionView()	Which screen to render

Only initiated sessions can start a new payment (isSessionActiveForPayments). After completion (or most other terminal views), call restartSession() or the next Wallets / Coinbase / Exchange Pay call hits SESSION_NOT_ACTIVE.

API statuses (SessionStatus)

Status	Meaning
initiated	Ready for payment — maps to view active
awaitingConfirmation	Payment in progress — waiting screen, or completed if transactionData is already present
awaitingEmailConfirmation	User must confirm email
completed	Payment finished — success / restart
failed	Payment failed
cancelled	Session cancelled — treat as expired in UI
rejected	Region / geo rejection (view.country, view.rejectReason)

UI views (SessionViewType)

View	When	Suggested UI
active	No session yet, or status initiated	Your normal app (payment methods, Wallets, Coinbase, Exchange Pay)
completed	Status completed, or awaitingConfirmation with transactionData	Success summary + Start new session (restartSession)
awaitingConfirmation	Status awaitingConfirmation without transaction data yet	Waiting / “payment processing”
awaitingEmailConfirmation	Status awaitingEmailConfirmation	Ask the user to confirm email
expired	Status cancelled	Session expired + restart
failed	Status failed	Failure message + restart
rejectedRegion	Status rejected	Region not supported — prefer view.rejectReason (may contain \n; use white-space: pre-line), fall back to view.country
rejectedCompliance	Runtime session:rejected (compliance)	Compliance blocked — no restart of the same session
maintenance	Maintenance flag enabled (wins over status)	Maintenance / try later

completed may include optional view.transaction when the SDK can show a completed-transaction screen. For success details, also use client.wallets.transfer.getCompletedTransactionSummary() (then ensure fees / rates), client.coinbase.getCompletedTransactionSummary(), client.exchangePay.getCompletedTransactionSummary(), or client.cashApp.getCompletedTransactionSummary().

This is the Swapped session. Coinbase OAuth JWT expiry is separate (COINBASE_SESSION_EXPIRED / coinbase:sessionExpired) — reconnect Coinbase, do not confuse it with expired above.

Read the view

import {
  SessionViewType,
  createSwappedConnectClient,
  isSessionActiveForPayments,
} from '@swapped/connect-sdk';

const client = createSwappedConnectClient({ sessionId: 'your-session-id' });
await client.loadSession();

const view = client.getSessionView();
const session = client.getSession();

console.log(view.type);
console.log(session?.session.status);
console.log(isSessionActiveForPayments(session)); // true only when status is initiated

Subscribe when the classified view changes:

client.on('sessionView:changed', ({ view }) => {
  renderForView(view);
});

client.on('session:rejected', () => {
  // usually becomes REJECTED_COMPLIANCE
});

client.on('maintenance:changed', () => {
  // may become MAINTENANCE
});

Render by view

import { SessionViewType, type SessionView } from '@swapped/connect-sdk';

function renderForView(view: SessionView) {
  switch (view.type) {
    case SessionViewType.Active:
      // payment methods → Wallets / Exchange Pay / Cash App / Coinbase
      break;
    case SessionViewType.Completed: {
      const wallets = client.wallets.transfer.getCompletedTransactionSummary();
      const coinbase = client.coinbase.getCompletedTransactionSummary();
      const exchangePay = client.exchangePay.getCompletedTransactionSummary();
      const cashApp = client.cashApp.getCompletedTransactionSummary();
      // show provider summary if present, else generic completed + restart
      break;
    }
    case SessionViewType.RejectedRegion:
      // prefer view.rejectReason (may include \n); fall back to view.country
      break;
    case SessionViewType.RejectedCompliance:
      // compliance blocked
      break;
    case SessionViewType.Expired:
      // expired + restartSession()
      break;
    case SessionViewType.Failed:
      // failed + restartSession()
      break;
    case SessionViewType.AwaitingConfirmation:
      // waiting for confirmation
      break;
    case SessionViewType.AwaitingEmailConfirmation:
      // confirm email
      break;
    case SessionViewType.Maintenance:
      // try later
      break;
  }
}

Lifecycle

1. createSwappedConnectClient({ sessionId }) → loadSession()
2. While view is active, list payment methods and run Wallets, Exchange Pay, Cash App, or Coinbase
3. When the view leaves active, show the matching screen above
4. restartSession() before another payment
5. destroy() when tearing down

await client.restartSession(); // new payment after completion / expiry / failure
client.destroy();

Force reload

Call loadSession() once at bootstrap. You almost never need to call it again — socket events and payment completion already refresh the session and getSessionView().

To force a fresh GET (for example after a long-backgrounded tab missed events):

await client.loadSession({ forceRefetch: true });
// or
await client.loadSession(sessionId, { forceRefetch: true });

Most apps will not need forceRefetch.

Errors

Code	When	What to do
SESSION_NOT_ACTIVE	Start payment when status ≠ initiated	Show completed / terminal UI; restartSession()
SESSION_REQUIRED	Action needs a loaded session (connect, withdraw, create order, …)	loadSession() first
SESSION_ID_REQUIRED	Missing id on load / restart	Pass a valid sessionId
WEBSOCKET_CONNECTION_FAILED	Live session / order socket failed (error event, context: 'websocket')	Allow apiBaseUrl in connect-src including wss: — see Browser requirements

Related

• Getting started
• Client
• Creating a session
• Browser requirements
• Events
• Concepts
• React track: Session