Skip to main content
This page explains how to handle runtime and integration errors across wallet, card, and 3DS components. Use these patterns to show clear user messages, keep checkout recoverable, and capture diagnostics for backend and support teams.

​
Wallet Error Handling

Wallet elements expose onError and onCancel handlers. 
onError: (error) => {
  console.error('Wallet error', error.code, error.message)
},
onCancel: () => {
  console.log('User cancelled wallet flow')
}
Possible error codes:
  • PROVIDER_ERROR
  • VALIDATION_ERROR
  • CONFIGURATION_ERROR
  • UNKNOWN

​
Card and 3DS Mount Errors

mount() throws if the target is invalid or if the provider component fails to mount. 
try {
  const card = await rinne.elements.card()
  await card.mount('#missing-container')
} catch (error) {
  console.error('Mount failed:', error)
}

try {
  const threeDSecure = await rinne.elements.threeDSecure()
  await threeDSecure.mount('')
} catch (error) {
  console.error('3DS mount failed:', error)
}

​
Common Failure Points

The selector passed to mount() does not match a DOM node. Ensure the element exists before mounting.
Check HTTPS, browser/device compatibility, and Apple Pay domain verification.
Your onCapture handler likely failed without calling fail(). Always call fail() when backend charge creation fails.
Verify that sessions are not expired. Sessions expire 1 hour after creation. Request a new session and remount on retry.
Always check auth_status from your backend session response before mounting the 3DS element. A FAILED status means the card was rejected before the authentication flow could start — do not mount and do not proceed with payment. Only mount for ACTION_REQUIRED; the SDK handles frictionless and challenge flows internally from there.

​
Debug Logging Pattern

const log = (event: string, payload?: unknown) => {
  console.log(`[rinne-checkout] ${event}`, payload)
}

const walletHandlers = {
  onCapture: async (payload, fail) => {
    log('wallet.capture', payload)
    try {
      await charge(payload)
      log('wallet.capture.success')
    } catch (error) {
      log('wallet.capture.failure', error)
      fail({ message: error instanceof Error ? error.message : 'Charge failed' })
    }
  },
  onError: (error) => log('wallet.error', error),
  onCancel: () => log('wallet.cancel')
}