Initialization

If you are upgrading from SDK 1.0, focus on the sections below that changed: APMs configuration (zoned layout), Form configuration (enabled), and the top-level appearance object (see Appearance API).

Initialize the payment UI: Revup.mount() + RevupSession.set()

The 1.2 version use Revup.mount() + RevupSession.set(), which returns a RevupSession.

const revupSession = await window.Revup.mount({
merchantDomain: window.location.origin,
apiKey: apiKey,
containerId: 'revup-container',
orderId: orderId,
});
await revupSession.set({ orderId: newOrderId });
await revupSession.set({ appearance: { theme: 'dark' } });
await revupSession.set({ apiKey: newApiKey });

revupSession.set() inspects which fields changed and picks the cheapest path automatically:

FIELD	PATH	DESCRIPTION
merchantDomain	Cold (rebuild)	Full SDK rebuild, but handled internally by set().
apiKey	Cold (rebuild)	Full SDK rebuild, but handled internally by set().
containerId	Cold (rebuild)	Full SDK rebuild, but handled internally by set().
orderId	Hot	Re-fetches order config, re-initializes APMs, reuses the form iframe (no reload).
appearance	Hot	Applies CSS variables live, no rebuild.
form	Hot	Re-renders only what changed; the accordion collapsed state toggles without a rebuild.
apms	Hot	Diffs old vs new APM set — unaffected buttons keep their DOM/vendor SDK state.
userInfo	Hot	Re-synced without a rebuild.
language	Full re-init (same instance, not a full teardown)	Buttons/labels need consistent re-rendering.

set() returns an UpdateReport: { path: 'hot' | 'cold' | 'noop', changed, committed?, durationMs, coalesced? } — use it to confirm what actually happened.

Parameters: RevupOptions

PROPERTY	TYPE	REQUIRED	VALUE / DEFAULT	DESCRIPTION
containerId	string	Yes	'revup-container'	ID of the DOM element that will host the payment UI.
orderId	string	No*	'...'	Order identifier for the checkout session. Required on the first Revup.mount() + RevupSession.set() call unless it was already passed to RevupConfig. Hot-updatable: calling Revup.mount() + RevupSession.set() again with a different orderId on the same Revup instance re-fetches the order config and re-initializes APMs without recreating the object.
form	object	No	{...}	See Form configuration.
apms	object	No	{...}	See APMs configuration.
appearance	object	No	{ theme: "default", variables: {}, rules: {} }	Optional checkout styling via themes, variables, and rules. Replaces deprecated form.styles and form.buttonStyles. See the Appearance API.
language	string	No	'en-US'	BCP 47 language code for form labels, APM buttons, and placeholders. If omitted, the SDK detects the browser language and falls back to 'en-US'.

Supported language codes can be inspected with Revup.getAvailableLanguages().

Form configuration

PROPERTY	TYPE	DEFAULT	DESCRIPTION
enabled	boolean	true	When false, the card form and "Pay with card" button are not rendered.
collapsed	boolean	true	If true, the card form starts collapsed behind a card entry point; if false, it starts expanded. This is independent of how many APM buttons are configured.
showZipCode	boolean	false	Whether to show the ZIP/postal code field. Set to true to display it.
textDirection	string	'ltr'	Text direction for the whole RevUp widget. Only the exact lowercase 'rtl' mirrors; any other string (including 'RTL') resolves to 'ltr'. Not derived from language.
cardBrands	array	['visa', 'mastercard']	Card-brand icons shown in the card-number field before a brand is detected (not on the accordion button). Supported brands: 'visa', 'mastercard', 'american_express', 'unionpay', 'jcb', 'discover', 'diners_club', 'maestro', 'visa_electron', 'vpay', 'rupay', 'elo', 'elo_new', 'hipercard', 'verve', 'troy', 'mir', 'cartes_bancaires', 'girocard', 'dankort', 'bancontact', 'interac', 'bc_card', 'dinacard', 'cabal', 'napas', 'mada', 'knet', 'benefit'.
cardBrandIconPlacement	string	'input'	'input' shows the card-brand icons in the card-number field. 'button' shows the card-brand icons in the card payment CTA.
userInfo	object	No	Optional payer information for the hosted card form. Pass at the top level of Revup.mount() + RevupSession.set() next to form and apms. See User info (userInfo) below.

info

Any unrecognized key inside form is rejected at runtime and logged as "key is not a valid option, default value was set instead.".

There is no form.styles or form.buttonStyles option. Visual styling of the form including the submit button's colors, height, and border radius is configured through the top-level appearance option passed to Revup.mount() + RevupSession.set(), not through form. Submit-button height is clamped 44–55 px and border radius 0–60 px by the Appearance API see the Appearance API.

User info (userInfo)

Optional object on Revup.mount() + RevupSession.set(). Use it to collect payer email on the hosted credit card form.

PROPERTY	TYPE	VALUE	DESCRIPTION
email	object	{ ... }	Nested settings for the email field. Omitted unless you need email collection.
email.required	boolean	false	When true, the hosted form shows an email field above the card inputs and requires a valid address before pay.
email.value	string	''	Pre-fills the email field when it is shown.

If the shopper provides an email, the payment request body includes payerEmail (trimmed). If email.required is false or omitted, the email field is not shown.

APMs configuration

The apms object configures alternative payment method buttons in three optional zones. Each zone is an array of ApmEntry objects; the SDK skips a zone when it is empty or contains no available methods.

A payment method may appear in only one zone. Duplicates across zones are de-duplicated with priority primary > secondary > other.

PROPERTY	TYPE	DESCRIPTION
primary	ApmEntry[]	APM buttons rendered above the credit-card accordion. Maximum of 4 entries (extra entries are dropped).
secondary	ApmEntry[]	Compact 2-column grid rendered below the card accordion, preceded by an "Or pay with" divider. Maximum of 4 entries. Hidden when empty. By default we set all APMs light theme color.
other	ApmEntry[]	Collapsed "+ N more payment methods" dropdown below the secondary grid. Unlimited entries. Hidden when empty. By default we set all APMs light theme color.

ApmEntry fields

PROPERTY	TYPE	REQUIRED	DESCRIPTION
name	string	Yes	APM identifier (e.g. 'apple_pay', 'google_pay', 'paypal', 'stripe_link', 'amazon_pay', 'ideal', 'sepa_debit', 'pix'. ). credit_card is not valid here; configure the card flow through form.
type	string	No	Vendor-specific button style variant. Apple Pay supports add-money, book, buy, check-out, continue, contribute, donate, order, pay, plain, reload, rent, set-up, subscribe, support, tip, top-up. Google Pay supports book, buy, checkout, donate, order, pay, plain, subscribe. PayPal supports paypal, checkout, buynow, pay, installment. Stripe Link and Amazon Pay do not use type. Ignored for iDeal.
color	string	No	Vendor-specific button color. Apple Pay: any CSS color, or the presets 'black', 'white', 'white-outline' (auto-selected from background contrast if omitted). Google Pay: 'default', 'black', 'white'. PayPal: 'gold', 'blue', 'silver', 'white', 'black'. Stripe Link and Amazon Pay do not support color customization.
capabilityDetection	boolean	No	When true, the APM performs a device/browser capability check before rendering hiding the button if unsupported. Defaults to false. Only honoured by Apple Pay and Google Pay. If detection fails, the SDK dispatches apm.unavailable for that method. Ignored for iDeal.

Supported color values by APM:

• apple_pay: any valid CSS color (e.g. #1f6feb), or presets black, white, white-outline. If omitted in primary, the SDK auto-selects black or white from background contrast.
• google_pay: default, black, white.
• paypal: gold, blue, silver, white, black.
• stripe_link: no color customization (value is ignored).
• amazon_pay: no color customization (value is ignored).
• iDEAL: white or dark (default dark)

Secondary / other defaults: methods listed only in secondary or other (not in primary) without an explicit color receive Apple Pay white-outline, Google Pay white, iDeal white, and PayPal white.

info

apms no longer accepts a flat enabled, buttonTypes, capabilityDetection shape APM identifiers, button style variants, colors, and capability detection are all set per-entry inside primary, secondary, other, as shown above.

Natively-Served Methods: Styling

• The collapsed accordion header follows submitButton* appearance variables (dark) or fixed light-surface colors (white), controlled by ApmEntry.color.
• The expanded panel reuses card accordion open-state tokens (cardButtonBorderWidth, cardButtonBorderColorOpen, etc.).
• Stable CSS hooks: .apms-accordion__header, .apms-ideal-body, .apms-native-button.apms-ideal-button, among others.

APM capability detection

The SDK supports optional capability detection for wallet APMs during initialization.

Behavior:

• If an APM entry sets capabilityDetection: true, the SDK runs a support check before rendering that button.
• If capabilityDetection is omitted or false (the default), the check is skipped and the button renders unconditionally.
• Apple Pay uses canMakePayments() and may run canMakePaymentsWithActiveCard() when merchantIdentifier is available.
• Google Pay uses isReadyToPay().
• If detection fails, the SDK dispatches apm.unavailable for that method and does not render an unusable button.

Complete initialization example

await Revup.mount({
  containerId: 'revup-container',
  language: 'en-US',
  appearance: {
    theme: 'default',
    variables: {
      submitButtonBackgroundColor: '#306de5',
      submitButtonTextColor: '#FFFFFF',
      submitButtonHeight: '44px',
      submitButtonBorderRadius: '16px'
    }
  },
  form: {
    collapsed: false,
    showZipCode: true,
    cardBrands: ['visa', 'mastercard', 'american_express']
  },
  userInfo: {
    email: { required: true, value: '' }
  },
  apms: {
    primary: [
      { name: 'apple_pay', color: '#111111', capabilityDetection: true },
      { name: 'google_pay', color: 'white', capabilityDetection: true },
      { name: 'paypal', type: 'checkout', color: 'blue' }
    ],
    secondary: [
      { name: 'amazon_pay' },
      { name: 'stripe_link' }
    ],
    other: [
      // Additional APMs hidden behind the "+ N more" toggle
    ]
  }
});

Minimal initialization

const revupSession = await window.Revup.mount({
merchantDomain: window.location.origin,
apiKey: apiKey,
containerId: 'revup-container',
orderId: orderId,
});
await revupSession.set({ orderId: newOrderId });
await revupSession.set({ appearance: { theme: 'dark' } });
await revupSession.set({ apiKey: newApiKey });

If the container id is missing from the DOM, the initialisation throws:

Container with id: <containerId> not found, please check if the container is present in the DOM

Optional: Get available APMs

To know which APMs are available for the current merchant/session (e.g. for debugging or UI logic), you can call:

const paymentMethods = await revup.getApmsAvailable();
// e.g. ['apple_pay', 'google_pay', 'paypal', 'stripe_link', 'amazon_pay', 'pix', 'ideal', 'sepa_debit']

This can be called before mount() (as in the reference integration) or whenever you need to inspect merchant-enabled APMs for the current session.

info

This method is optional and has an additional loading time. It can be called in parallel to loading the SDK as it is not necessary for its initialization.

Cleanup and re-init

Switching to a new order

With the Session API:

await session.set({ orderId: nextOrderId });

With the constructor flow:

await revup.init({ containerId: 'revup-container', orderId: newOrderId });

The orderId you pass to init() wins. If you omit it, the SDK silently reuses the previous order — no warning is emitted, so pass it explicitly whenever it changes.

Full teardown

stopListening();   // 1. remove your event listener
revup.destroy();   // 2. tear the SDK down

destroy() does what clearing the container cannot: it tears down the handlers and the card iframe, resets the accordion coordinator, empties the container, clears the appearance CSS custom properties and parent-page rules, removes the rel="preconnect" links the SDK injected into your head, and detaches the document-level keyboard and pointer listeners used by the accordion rows. Skipping it leaks those listeners.

destroy() does not remove your onRevupMessage event listener — that's a separate subscription you own. Call stopListening() (the function returned by onRevupMessage()) yourself before or alongside destroy(); otherwise your listener stays attached even after the SDK is torn down.

Never use container.innerHTML = '' as teardown. Earlier revisions of this guide recommended it; it is not a sufficient teardown.

Do not reuse the same Revup instance for a different merchant configuration (merchantDomain / apiKey) without destroying it first.

Reference integration flow (summary)

The reference integration does the following:

1. Load script — Use a loader component that injects the RevUp script and fires onRevupSDKLoaded when ready.
2. Wait for SDK + orderId — Only run renderForm() when sdkLoaded && orderId (and optionally form options).
3. Single listener — Use revup.onRevupMessage(onRevupMessageHandler) or document.addEventListener('onRevupMessage', onRevupMessageHandler) to capture all events.
4. Config — Build config from environment (env), apiKeys, and current orderId; set merchantDomain from window.location.host (or override for local/dev).
5. Create and init — revup = new Revup(config) then await Revup.mount({ containerId: 'revup-container', form: { ...formOptions } }).
6. Optional — Call revup.getApmsAvailable() before mount() or whenever you need to inspect merchant-enabled APMs for the current session.
7. Cleanup — On unmount or before re-init with a new merchantDomain / apiKey, abort the event listener and call revup.destroy() (do not manually clear the container's inner HTML — destroy() also removes appearance CSS variables and preconnect hints).