Rinne API Documentation

Wallet Elements provide Apple Pay and Google Pay buttons backed by the same transaction object and callback contract. Use them to collect tokenized wallet payment data and forward encrypted payloads to your backend for transaction processing.

Supported Wallet Elements

const applePay = await rinne.elements.applePay(transaction, options)
const googlePay = await rinne.elements.googlePay(transaction, options)

Both elements support the same core options (button, onCapture, onError, onCancel). googlePay() also supports colorScheme and allowedAuthMethods.

Options

interface WalletMountOptions {
  button?: {
    color?: 'black' | 'white'          // default: 'black'
    locale?: 'pt' | 'en' | 'es'        // default: 'pt'
    type?: 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe' // default: 'plain'
    borderRadius?: number
    size?: {
      width: string | number           // default: '100%'
      height: string | number          // default: '40px'
    }
  }
  colorScheme?: 'light' | 'dark'      // Google Pay only: iframe root color-scheme
  allowedAuthMethods?: [GooglePayAuthMethod, ...GooglePayAuthMethod[]] // Google Pay only
                                      // default: ['THREE_DS'] — never empty
  onCapture?: (payload, fail) => Promise<void> | void
  onError?: (error) => void
  onCancel?: () => void
}

Event Lifecycle

Stage	Callback	What you should do
User authorizes wallet payment	`onCapture(payload, fail)`	Send `payload.card_data` to your backend and create/confirm the transaction
Backend processing fails	`fail({ message })`	Call `fail()` so the wallet UI exits processing state and can retry
User closes wallet sheet	`onCancel()`	Restore your checkout UI and keep cart state
Provider or SDK issue	`onError(error)`	Show a fallback payment method and log details for debugging

Button Behavior

Capability	Apple Pay	Google Pay
Button color	`black`, `white`	`black`, `white`
Button types	`book`, `buy`, `checkout`, `donate`, `order`, `pay`, `plain`, `subscribe`	Same as Apple Pay
Locale input	`pt`, `en`, `es`	`pt`, `en`, `es`

Wallet Availability

Apple Pay and Google Pay buttons are not rendered when the environment does not support them. This happens silently — mount() resolves without rendering any visible element. Conditions that prevent rendering include:

Non-HTTPS origin
Browser or device without wallet support
No card in the wallet that is eligible under your configuration
Apple Pay domain not verified (Apple Pay only)
Google Pay wallet holding only account-saved cards, on the default allowedAuthMethods: ['THREE_DS'] — enabling UNAUTHENTICATED removes this case

Design your checkout layout so it gracefully handles an empty wallet button slot, or check support before mounting.

Apple Pay Domain Verification

Apple Pay only appears on domains that are verified with Apple. If your domain is not verified, the Apple Pay button will not render.

Before going live:

Download the Apple Pay domain association file. Keep the filename exactly as it downloads — apple-developer-merchantid-domain-association with no extension.
Host it on every domain and subdomain where Apple Pay is used, at the exact path /.well-known/apple-developer-merchantid-domain-association, served over HTTPS.
Let Rinne know which domains and subdomains to register so they can be submitted to Apple for verification.

If the file is removed, replaced, or becomes unavailable, Apple can invalidate the domain and Apple Pay will stop working until the domain is verified again.

onCapture Contract

onCapture gives you encrypted wallet card data, payment method, and the transaction object you created.

interface WalletSuccessPayload {
  card_data: CardData
  payment_method: 'CREDIT_CARD' | 'DEBIT_CARD'
  transaction: EvTransaction
}

card_data is a discriminated union, not a single flat interface. wallet_type separates the wallets, and for Google Pay authentication_type separates its two shapes:

interface CardDataCommon {
  expiry_month: string          // "MM"
  expiry_year: string           // "YYYY"
  brand?: string
  last_digits?: string
  issuer?: string
  segment?: string
  country?: string
  display_name?: string
}

// Apple Pay always authenticates on-device, so it has a single shape.
interface ApplePayCardData extends CardDataCommon {
  wallet_type: 'APPLE_PAY'
  network_token: string
  cryptogram: string
  token_provider: string
  eci?: string | null
  device_id?: string            // Apple Pay only
  authentication_type?: '3DS'
}

// Google Pay under THREE_DS — device-tokenized, liability shifts to the issuer.
interface GooglePayThreeDsCardData extends CardDataCommon {
  wallet_type: 'GOOGLE_PAY'
  authentication_type: '3DS'
  network_token: string
  cryptogram: string
  token_provider: string
  eci?: string | null
}

// Google Pay under UNAUTHENTICATED — encrypted PAN, no liability shift.
interface GooglePayUnauthenticatedCardData extends CardDataCommon {
  wallet_type: 'GOOGLE_PAY'
  number: string
  authentication_type?: never
}

type CardData =
  | ApplePayCardData
  | GooglePayThreeDsCardData
  | GooglePayUnauthenticatedCardData

Fields absent from a member are left off instead of typed as optional, so reading one before narrowing is a compile error rather than a silent undefined:

onCapture: ({ card_data }) => {
  if (card_data.wallet_type === 'APPLE_PAY') {
    card_data.cryptogram // string
  } else if (card_data.authentication_type === '3DS') {
    card_data.cryptogram // string — device-tokenized Google Pay
  } else {
    card_data.number     // string — encrypted PAN, no liability shift
  }
}

Narrow on wallet_type before authentication_type. Apple Pay sets authentication_type to '3DS' only on some captures, so one that arrives without it would otherwise fall into the branch you wrote for the unauthenticated Google Pay shape.

GooglePayMountOptions is generic in the methods you allow, so onCapture receives only the shapes your selection can produce. With allowedAuthMethods omitted or set to ['THREE_DS'], you get GooglePayThreeDsCardData directly and no narrowing is needed.

payment_method is inferred from wallet funding data and defaults to CREDIT_CARD when funding type is not provided by the provider.

onCapture: async (payload, fail) => {
  try {
    await sendToBackend(payload.card_data, payload.payment_method, payload.transaction)
  } catch (error) {
    fail({ message: error instanceof Error ? error.message : 'Payment failed' })
  }
}

If backend processing fails, call fail() inside onCapture. Without it, the wallet may stay in a processing state.

allowedAuthMethods (Google Pay)

allowedAuthMethods selects which card credentials Google Pay may return. It defaults to ['THREE_DS'] — only device-tokenized cards carrying a 3DS cryptogram. Leave the option out and that is what you get, so nothing widens what you accept unless you ask for it.

Value	Credential	Liability shift
`THREE_DS` (default)	Card tokenized on the device: `network_token` + `cryptogram`	Yes — shifts to the issuer
`UNAUTHENTICATED`	Card saved to the shopper’s Google account: encrypted PAN	No

Enable UNAUTHENTICATED only if your organization has made that call, and consider running 3DS on those payments.

const googlePay = await rinne.elements.googlePay(transaction, {
  allowedAuthMethods: ['UNAUTHENTICATED', 'THREE_DS'],
  ...walletHandlers
})

Accepting UNAUTHENTICATED means no liability shift — the same risk profile as a keyed card without 3DS. The upside is that shoppers whose wallet holds only account-saved cards (common on desktop) can pay instead of seeing an empty Google Pay sheet.

THREE_DS and UNAUTHENTICATED are the only values the option accepts. Note that the THREE_DS option value is not the same string as authentication_type: '3DS' in the captured card_data, which is the API’s wire value.

Payload differences

The two methods return different card_data shapes:

`card_data` field	`THREE_DS`	`UNAUTHENTICATED`
`network_token`	`token.number`	—
`number`	—	encrypted PAN
`expiry_month` / `expiry_year`	present	present
`cryptogram` / `eci` / `token_provider`	present	—
`authentication_type`	`'3DS'`	—
`brand`, `last_digits`, `display_name`, `wallet_type`	present	present

The missing authentication_type is the marker to branch on server-side if you apply different risk rules to unauthenticated payments. Both shapes go to the standard API host — the PAN is already encrypted before it reaches the SDK, so the PCI endpoints are not involved.

A malformed payload now fails the payment instead of being downgraded. A Google Pay token missing tokenServiceProvider throws Google Pay network token is missing tokenServiceProvider rather than falling back to the PAN shape, and a payload with no card at all throws Google Pay response must contain either a network token or a card number. Both surface through fail() like any other capture error.

colorScheme (Google Pay)

Use colorScheme to align the Google Pay iframe with your page theme.

const colorScheme =
  document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light'

const googlePay = await rinne.elements.googlePay(transaction, {
  button: { color: 'black', type: 'pay', locale: 'pt' },
  colorScheme,
  ...walletHandlers
})

Mount and Unmount

const element = await rinne.elements.applePay(transaction, options)
const mounted = await element.mount('#apple-pay-container')

// Later
mounted.unmount()

mount() accepts either a CSS selector or an HTMLElement.

Mount Errors

mount() throws if the target is missing or the provider cannot render the wallet button.

try {
  const applePay = await rinne.elements.applePay(transaction, options)
  await applePay.mount('#missing-wallet-slot')
} catch (error) {
  console.error('Wallet mount failed', error)
}

Full Wallet Example

const transaction = await rinne.transaction.create({
  amount: 1999,
  lineItems: [{ label: 'Demo Product', amount: 1999 }]
})

const colorScheme =
  document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light'

const walletHandlers = {
  onCapture: async (payload, fail) => {
    try {
      const response = await fetch('/api/wallet/charge', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          cardData: payload.card_data,
          paymentMethod: payload.payment_method,
          amount: payload.transaction.details.amount
        })
      })

      if (!response.ok) {
        const body = await response.json()
        throw new Error(body.message ?? 'Charge failed')
      }
    } catch (error) {
      fail({ message: error instanceof Error ? error.message : 'Charge failed' })
    }
  },
  onError: (error) => console.error(error),
  onCancel: () => console.log('Cancelled')
}

const applePay = await rinne.elements.applePay(transaction, {
  button: { color: 'black', type: 'pay', locale: 'pt', borderRadius: 0 },
  ...walletHandlers
})
await applePay.mount('#apple-pay')

const googlePay = await rinne.elements.googlePay(transaction, {
  button: { color: 'black', type: 'pay', locale: 'pt', borderRadius: 0 },
  colorScheme,
  ...walletHandlers
})
await googlePay.mount('#google-pay')

Start here

Core SDK

Integration guides

Production

Wallet Elements

Supported Wallet Elements

Options

Event Lifecycle

Button Behavior

Wallet Availability

Apple Pay Domain Verification

onCapture Contract

allowedAuthMethods (Google Pay)

Payload differences

colorScheme (Google Pay)

Mount and Unmount

Mount Errors

Full Wallet Example

​Supported Wallet Elements

​Options

​Event Lifecycle

​Button Behavior

​Wallet Availability

​Apple Pay Domain Verification

​onCapture Contract

​allowedAuthMethods (Google Pay)

​Payload differences

​colorScheme (Google Pay)

​Mount and Unmount

​Mount Errors

​Full Wallet Example

Supported Wallet Elements

Options

Event Lifecycle

Button Behavior

Wallet Availability

Apple Pay Domain Verification

onCapture Contract

allowedAuthMethods (Google Pay)

Payload differences

colorScheme (Google Pay)

Mount and Unmount

Mount Errors

Full Wallet Example