Integration Guide

This guide explains how to integrate the Revup payment SDK (v1.1.0) 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, and additional methods arranged in primary, secondary, and other zones.

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', () => {
  // ...
});

Option A: Script tag with integrity (recommended for production)

Use the correct integrity value (SRI hash) provided for your environment.

<script
  type="text/javascript"
  charset="utf-8"
  src="https://your-cdn.example.com/path-prefix/major/minor/loader.js"
  crossorigin="anonymous"
  integrity="sha512-...">
</script>

Sandbox:

<script
  type="text/javascript"
  charset="utf-8"
  src="https://test.hosted.revuppayments.com/payments-widget/sdk/1/1/loader.js"
  crossorigin="anonymous"
  integrity="sha512-p3aYjpM7LAqoyPcAuKIyng60b6n0gySRi4mDK62VaMfSbVXCIw/AzxihAOUWzcQZ3OoGeKpSugWqonsfhcDoWA==">
</script>

Live:

<script
  type="text/javascript"
  charset="utf-8"
  src="https://hosted.revuppayments.com/payments-widget/sdk/1/1/loader.js"
  crossorigin="anonymous"
  integrity="sha512-KmQPezxKAxs8BaA/wedsUJsb7X2WQYDHZqaRrPIO/Qd1Wl9rFVLjnOUxKX5Ty81wcZOjz4kgKKP0epUKuNW7mA==">
</script>

Option B: Dynamic load (e.g. React)

// Load script
const script = document.createElement('script');
script.type = 'text/javascript';
script.charset = 'utf-8';
script.src = REVUP_SDK_URL; // e.g. env-specific URL
script.crossOrigin = 'anonymous';
if (INTEGRITY_HASH) script.integrity = INTEGRITY_HASH;
document.head.appendChild(script);

Only create the Revup instance and call init() after the script has loaded (e.g. when onRevupSDKLoaded has fired or when your sdkLoaded state is true).

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 init(). 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 config = {
  apiKey: apiKey,
  merchantDomain: window.location.host,
  orderId: orderId,
  // version: '2'  // optional
};
const revup = new Revup(config);

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 in the SDK 1.0 reference (event names and payloads are unchanged in 1.1).

Steps 5–7

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

8. 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/1/loader.js	sha512-F+iybktYITNESU9I1Okk1Hm63R7xbPxwvpWLS9zzNsl4ZBviUZ9eNSVsX/ZYx0+oLQk8QaT4n4GNE+f9HP1YIQ==
Live	https://hosted.revuppayments.com/payments-widget/sdk/1/1/loader.js	sha512-dkLtqmMnP0cbxtgr8FIz4YYV2/BdpswXDuZKCOtDcrz33DDFArqn3hATmWPvE7hzReSMZbJwtkbZqrbwaDZyNA==

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.