Integration Guide

This guide explains how to integrate the RevUp payment SDK into your merchant page. It is based on the Revup class API and a reference integration.

Overview

Revup is a meta-SDK that orchestrates:

Credit card form — Hosted in a sandboxed iframe, embedded in a connected card accordion slot.
Alternative Payment Methods (APMs) — Apple Pay, Google Pay, PayPal, Stripe Link, Amazon Pay, iDEAL, SEPA Direct Debit, and Pix when enabled for your merchant configuration.

The SDK exposes a single global constructor Revup and communicates with your page via the native DOM event onRevupMessage.

1. Load the SDK script

Load the Revup script from your CDN or build output. The script must be loaded before you instantiate Revup or call any of its methods.

Wait for a load event before creating Revup:

// Listen for SDK ready
window.addEventListener('onRevupSDKLoaded', () => {
  // ...
});

Script tag with integrity

Sandbox:

<script
  type="text/javascript"
  charset="utf-8"
  src="https://test.hosted.revuppayments.com/payments-widget/sdk/1/2/loader.js"
  crossorigin="anonymous"
  integrity="sha512-29BjlTVGhugMinJEYjCATVBHp5S9dHeINo+FakhOHp/oDT3NVrpDjXOTLdiKoXy2qH7qHrS47p/O6IeTBAQ5Ow==">
</script>

Live:

<script
  type="text/javascript"
  charset="utf-8"
  src="https://hosted.revuppayments.com/payments-widget/sdk/1/2/loader.js"
  crossorigin="anonymous"
  integrity="sha512-p+XPAb31C2DmYZIC7KLX9hX3164m9zIhBU0cMl7r1dwscf7HyPq3Ka4sDLaxWRZ5qblD1FGUwTc90nchJ9Xl/A==">
</script>

Integration via Loader (Pinned to a Minor Version, e.g. 1.2)

This is the integration model you are currently using. Your application loads our loader.js and is pinned to a Minor version. This follows a continuous delivery model, similar to Stripe's SDK, where you automatically receive all Patch releases within the selected Minor version.

Advantages

Automatic updates: You automatically receive Patch releases without any changes on your side.
Security fixes: Critical security updates, including fixes for third-party dependencies, are delivered automatically.
Bug fixes: Critical bug fixes are applied as soon as they are released.
Performance and UI improvements: You benefit from ongoing optimizations, such as accessibility enhancements, performance improvements, and small UX refinements.

Considerations

Because Patch releases may include minor UI or UX improvements, visual changes can occasionally trigger false positives in snapshot-based tests, even though the underlying functionality and API remain unchanged.

Direct Integration (Pinned to a Specific Patch Version, e.g. 1.2.1)

Disclaimer

Direct integration of the Revup SDK entails manual maintenance of patch versions. This means we cannot automatically or rapidly deploy security updates and bug fixes to your application. You must manually update SDK patch versions and download the integrity file (SRI) for each release, ensuring it is implemented correctly to maintain PCI compliance—this remains your responsibility. Finally, direct integration does not guarantee ongoing compatibility or maintenance of agreements with Revup SDK’s external providers, such as APMs (Stripe, PayPal, Apple Pay, Google Pay, etc.).

With this approach, you bypass the loader and reference a specific SDK bundle directly. This pins your integration to an exact Patch version, providing a predictable and stable environment.

To use version 1.2.1, include the corresponding script for each environment and initialize the SDK once it has loaded.

Test Environment

<script
  src="https://test.hosted.revuppayments.com/payments-widget/sdk/1/2/1/bundle-1.2.1.js"
  integrity="sha512-integrity-value"
  crossorigin="anonymous"
  onload="initializePaymentsWidget()">
</script>

Production Environment

<script
  src="https://hosted.revuppayments.com/payments-widget/sdk/1/2/1/bundle-1.2.1.js"
  integrity="sha512-integrity-value"
  crossorigin="anonymous"
  onload="initializePaymentsWidget()">
</script>

When you decide to upgrade (for example, from 1.2.1 to 1.3.0), you only need to:

Update the version in the script URL.
Replace the corresponding Subresource Integrity (SRI) hash.

The SRI hash can be obtained from the SDK manifest by replacing the bundle filename with the corresponding manifest, for example:

bundle-1.2.1.js
↓
manifest-1.2.1.json

Advantages

Complete version control: Your integration remains locked to a specific SDK release, ensuring a fully predictable environment.
Stable snapshot testing: Since no changes are introduced automatically, snapshot tests will only change when you explicitly upgrade the SDK.
Simple upgrade process: Upgrading only requires updating the version in the script URL and replacing the corresponding SRI hash.

Considerations

No automatic updates: Security patches, bug fixes, performance improvements, and other enhancements are not applied automatically.
Manual maintenance: You are responsible for periodically upgrading to newer versions in order to receive security updates, bug fixes, and new features.

2. Provide a container

Add a DOM element that will host the payment UI (APM buttons + form). The SDK will inject its layout into this element.

You can use any id; you will pass it as containerId in mount(). The example uses revup-container, which matches the reference integration.

<div id="revup-container"></div>

3. Configuration

Constructor config: `RevupConfig`

When creating the Revup instance, pass an object with:

PROPERTY	TYPE	REQUIRED	DESCRIPTION
merchantDomain	string	Yes	Your merchant domain (for example `window.location.host` or your production domain).
apiKey	string	Yes	API key for the environment (sandbox or live).
orderId	string	Yes	Order identifier for the current checkout session.
version	string	No	API version path segment. If omitted, the SDK uses the configured default API version, currently `"2"`.

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

4. Listen for events: `onRevupMessage`

All payment and form events are delivered as a single CustomEvent on document. The recommended helper unwraps the event detail for you:

const revupMessageCleanup = revup.onRevupMessage((event) => {
  // Handle Revup event
});

Use event.type and event.source to handle:

Form events — source === 'form' (e.g. initialized, validation.changed, payment.submitted, payment.action_required, payment.success, payment.failed).
APM events — source === 'apm' (e.g. payment.submitted, payment.success, payment.failed, payment.cancelled, apm.unavailable).

If you attach a native listener directly with document.addEventListener('onRevupMessage', handler), read the SDK event from event.detail.

const onRevupMessageHandler = (event) => {
  const { type, source, context, data, error } = event;
  switch (type) {
    case 'initialized':
      // Form/APM ready;
      break;
    case 'payment.submitted':
      // Submitted — the payment was submitted
      break;
    case 'payment.action_required':
      // DDC/3DS action required
      // url: data.transactionResult.response.action.url
      // status: data.transactionResult.response.transactionStatus
      // transactionId: data.transactionResult.response.transactionId
      break;
    case 'payment.success':
      // Success — use context.transactionId, context.orderId
      break;
    case 'payment.failed':
      // Declined or error — use error.message, error.statusCode
      break;
    case 'payment.cancelled':
      // User cancelled (APM)
      break;
    case 'apm.unavailable':
      // APM not available — context.apm, error.message
      break;
    default:
      break;
  }
};

const revupMessageCleanup = revup.onRevupMessage((event) => {
  onRevupMessageHandler(event);
});

For full event types, payload shape, and error names, see Event Handling.

Native iDeal Redirects
Native iDEAL leaves the page. On payment.action_required, the SDK navigates the top-level window itself (window.location.assign for GET, form POST otherwise).

The event is informational — no merchant action required — but anything needed should be persisted before the payer confirms.

Only https: URLs accepted (plus http: on localhost). Unsafe URLs produce payment.failed with no navigation.

Steps 5–7

Configuration changes for upgraders — mount() options, APM zones, and cleanup — are on Initialization.

Environment and URLs

Use the correct script URL and integrity hash for your environment (sandbox vs live).

ENVIRONMENT	URL	INTEGRITY HASH (SRI)
Sandbox	`https://test.hosted.revuppayments.com/payments-widget/sdk/1/2/loader.js`	`sha512-29BjlTVGhugMinJEYjCATVBHp5S9dHeINo+FakhOHp/oDT3NVrpDjXOTLdiKoXy2qH7qHrS47p/O6IeTBAQ5Ow==`
Live	`https://hosted.revuppayments.com/payments-widget/sdk/1/2/loader.js`	`sha512-p+XPAb31C2DmYZIC7KLX9hX3164m9zIhBU0cMl7r1dwscf7HyPq3Ka4sDLaxWRZ5qblD1FGUwTc90nchJ9Xl/A==`

Ensure CORS and Content Security Policy allow the SDK script and the form iframe origin.

The SDK uses an internal API base URL and form URL; these are set at build time. Your integration only needs to load the script and pass merchantDomain, apiKey, and orderId.

Overview​

1. Load the SDK script​

Script tag with integrity​

Integration via Loader (Pinned to a Minor Version, e.g. 1.2)​

Advantages​

Considerations​

Direct Integration (Pinned to a Specific Patch Version, e.g. 1.2.1)​

Test Environment​

Production Environment​

Advantages​

Considerations​

2. Provide a container​

3. Configuration​

Constructor config: RevupConfig​

4. Listen for events: onRevupMessage​

Environment and URLs​

Overview

1. Load the SDK script

Script tag with integrity

Integration via Loader (Pinned to a Minor Version, e.g. 1.2)

Advantages

Considerations

Direct Integration (Pinned to a Specific Patch Version, e.g. 1.2.1)

Test Environment

Production Environment

Advantages

Considerations

2. Provide a container

3. Configuration

Constructor config: `RevupConfig`

4. Listen for events: `onRevupMessage`

Environment and URLs