Rinne API Documentation

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

Target element not found

The selector passed to mount() does not match a DOM node. Ensure the element exists before mounting.

Wallet buttons not rendering

Check HTTPS, browser/device compatibility, and Apple Pay domain verification.

Google Pay sheet opens with no payment method

On the default allowedAuthMethods: ['THREE_DS'], a wallet holding only cards saved to the shopper’s Google account has nothing eligible to offer, and no SDK event fires. Enable UNAUTHENTICATED to accept those cards — at the cost of the liability shift. See allowedAuthMethods.

googlePay() throws at element creation

allowedAuthMethods was empty, or carried a value other than UNAUTHENTICATED and THREE_DS.

Wallet dialog stuck after authorization

Your onCapture handler likely failed without calling fail(). Always call fail() when backend charge creation fails.

3DS session errors

Verify that sessions are not expired. Sessions expire 1 hour after creation. Request a new session and remount on retry.

3DS proceeds despite FAILED auth_status

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')
}

Start here

Core SDK

Integration guides

Production

Errors and Debugging

Wallet Error Handling

Card and 3DS Mount Errors

Common Failure Points

Debug Logging Pattern

​Wallet Error Handling

​Card and 3DS Mount Errors

​Common Failure Points

​Debug Logging Pattern

Wallet Error Handling

Card and 3DS Mount Errors

Common Failure Points

Debug Logging Pattern