Events (Core)

Subscribe with client.on. Each call returns an unsubscribe function.

Common listeners

For which screen to show (active / completed / …), use client.getSessionView() and sessionView:changed.

const offLoaded = client.on('session:loaded', ({ session }) => {
  // session ready - show payment methods
})

client.on('session:refreshed', () => {
  // session updated after payment progress
})

client.on('sessionView:changed', ({ view }) => {
  // re-render from view.type - see Session guide
})

client.on('error', error => {
  // show error UI - WEBSOCKET_CONNECTION_FAILED is emitted here
  // (context: 'websocket') when connect-src blocks the live socket
})

client.on('transaction:updated', ({ transaction }) => {
  // tx hash / status changed
})

// later
offLoaded()

Wallets

client.on('wallets:connected', ({ connection }) => {
  /* connection.walletId */
})
client.on('wallets:disconnected', ({ walletId, reason }) => {
  /* … */
})
client.on('wallets:pairingUri', ({ uri, deeplinkUrl }) => {
  /* QR / open-in-wallet */
})
client.on('wallets:transferStatus', event => {
  event.status
})

Full guide: Wallets → Events.

Exchange Pay

client.on('exchangePay:orderUpdated', ({ sessionId, order }) => {
  /* refresh checkout */
})
client.on('exchangePay:orderCompleted', () => {
  /* success screen */
})
client.on('exchangePay:orderExpired', () => {
  /* expired UI */
})
client.on('exchangePay:formattedOrderUpdated', ({ formattedOrder }) => {
  /* quote loaded */
})

Full guide: Exchange Pay → Events.

Cash App

client.on('cashApp:orderCompleted', () => {
  /* success screen */
})
client.on('cashApp:orderFailed', () => {
  /* failed UI */
})
client.on('cashApp:orderExpired', () => {
  /* expired UI */
})
client.on('cashApp:orderReset', () => {
  /* local order cleared */
})

Full guide: Cash App → Events.

Coinbase

client.on('coinbase:connected', () => {
  /* show balances */
})
client.on('coinbase:disconnected', () => {
  /* show connect again */
})
client.on('coinbase:sessionEnsured', () => {
  /* token validated / refreshed */
})
client.on('coinbase:sessionExpired', () => {
  /* reconnect */
})
client.on('coinbase:withdrawalCompleted', () => {
  /* success screen */
})
client.on('coinbase:cooldownChanged', ({ isInCooldown, remainingMs }) => {
  // Fires when cooldown begins, every second while active, and when it ends.
  // Disable startWithdrawal UI while isInCooldown (confirmWithdrawal is not blocked).
})

Cooldown details: Coinbase → Cooldown.

Restart / destroy

await client.restartSession() // new payment after completion
client.destroy() // tear down