Skip to main content
The Reveal Card widget allows you to securely display sensitive card information — card number (PAN), security code (CVV), and expiration date — directly in your application. All sensitive data is fetched and rendered in an isolated iframe, helping reduce your PCI scope.
The <card-reveal-widget> element has been renamed to <reveal-card>. The old element name continues to work via a backwards-compatible alias but will be removed in a future major version. Please update your integration to use <reveal-card>.
Reveal Card Front
Reveal Card Back

​
Step 1: Load the Widget Script

Load the Reveal Card widget script into your page: 
<script
  type="module"
  src="https://assets.synctera.com/widgets/reveal-card/v1.1.1/index.js"
></script>

​
Step 2: Get a Widget Token

Request a widget token for revealing card details: 
curl -X GET "https://api.synctera.com/v2/cards/{card_id}/widget_token?widget_type=REVEAL" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json"
Widget tokens expire after 5 minutes and are scoped to a specific card. Generate a new token on each page load or when the user initiates a new reveal action.

​
Step 3: Add the Widget Component

Add the <reveal-card> web component to your page: 
<reveal-card
  token="your-widget-token"
  env="production"
></reveal-card>

​
Configuration Options

PropertyTypeRequiredDefaultDescription
tokenstringYes-Widget token obtained from the API
envstringYes-Environment: sandbox or production
themestringNo"default"Theme preset: "default" or "night-shift"
stylesstringNo{}JSON string of design tokens for visual customization
card-sidestringNo"front"Which side to show initially: "front" or "back"
card-formstringNo"physical"Card form factor: "physical" or "virtual"
card-typestringNo""Card type label displayed on the card (e.g., "DEBIT", "CREDIT")
last-fourstringNo""Last 4 digits of PAN, shown on the card front
emboss-namestringNo""Cardholder name displayed on the card front (line 1)
emboss-name-twostringNo""Optional second emboss line displayed below the cardholder name in a smaller font (e.g., business name)
card-networkstringNo"visa"Card network: "visa" or "mastercard"
show-togglebooleanNofalseRenders a built-in toggle to reveal/hide card details
toggle-labelstringNo""Custom label text for the built-in toggle
custom-labelsstringNo"{}"JSON string of custom labels

​
Card Side and Form

The widget renders a visual card with front and back views: 
<reveal-card
  token="your-token"
  env="production"
  card-side="front"
  last-four="1234"
  emboss-name="Jane Doe"
  emboss-name-two="Acme Corp"
  card-type="DEBIT"
  card-network="visa"
></reveal-card>

​
Built-in Toggle

Set show-toggle to render a toggle switch below the card that triggers the card reveal: 
<reveal-card
  token="your-token"
  env="production"
  show-toggle
  toggle-label="Show card details"
></reveal-card>

​
Custom Labels

Customize the labels displayed in the widget: 
<reveal-card
  token="your-token"
  env="production"
  custom-labels='{
    "panLabel": "Card Number",
    "cvvLabel": "Security Code",
    "expiryLabel": "Expires",
    "retryButtonText": "Retry",
    "toggleLabel": "Show Card Details",
    "cardholderPlaceholder": "CARDHOLDER"
  }'
></reveal-card>
Available custom label keys:
  • panLabel - Card number label (back side)
  • cvvLabel - CVV label (back side)
  • expiryLabel - Expiration date label (back side)
  • retryButtonText - Error state retry button text
  • toggleLabel - Built-in toggle label text
  • cardholderPlaceholder - Placeholder text when emboss-name is empty

​
Event Handling

The widget dispatches events for both initialization and card reveal outcomes:
  • load — The widget finished initializing and is ready to use.
  • error — The widget failed to initialize (network/CSP failure or handshake timeout).
  • success — Card details retrieved successfully.
  • failure — Card reveal failed (API error, timeout, etc.).
  • copy — A card field value was copied to the clipboard.
You can subscribe with addEventListener or by assigning the matching callback property:
EventaddEventListenerCallback property
Initialization successwidget.addEventListener('load', fn)widget.onLoad = fn
Initialization failurewidget.addEventListener('error', fn)widget.onError = fn
Reveal successwidget.addEventListener('success', fn)widget.onSuccess = fn
Reveal failurewidget.addEventListener('failure', fn)widget.onFailure = fn
Field copied to clipboardwidget.addEventListener('copy', fn)not exposed as a property

​
Load Event

Dispatched once when the widget has finished initializing and is ready to use. Use this to reveal the widget UI only after it’s ready, or to dismiss a loading placeholder. Fires exactly once per iframe lifecycle.
PropertyTypeDescription
instanceIdstringUnique ID for this widget instance
<reveal-card id="reveal-widget" token="your-token" env="production"></reveal-card>
<script>
  document.getElementById('reveal-widget').addEventListener('load', (event) => {
    const { instanceId } = event.detail;
    console.log('Widget ready', instanceId);
  });
</script>

​
Error Event

Dispatched once when the widget fails to initialize — either because the underlying iframe could not load (network failure, blocked by Content Security Policy, etc.) or because the iframe loaded but never completed its handshake within 5 seconds. This is distinct from the failure event, which signals that a card reveal API call failed after the widget was already running.
PropertyTypeDescription
errorstringHuman-readable error message (safe to display to end users)
failedFieldsstring[]Logical surfaces that failed to initialize. The Reveal Card widget has a single display surface, so this is always ['display-controller'].
instanceIdstringUnique ID for this widget instance
<script>
  document.getElementById('reveal-widget').addEventListener('error', (event) => {
    const { error, failedFields } = event.detail;
    console.error('Widget initialization failed:', error, failedFields);
    // Show error UI or offer a retry button
  });
</script>

​
Success Event

Dispatched when card details are successfully retrieved and rendered inside the widget’s secure iframe. Sensitive card data (PAN, CVV, expiration) is never exposed to the host page.
PropertyTypeDescription
instanceIdstringUnique ID for this widget instance
<reveal-card id="reveal-widget" token="your-token" env="production"></reveal-card>
<script>
  document.getElementById('reveal-widget').addEventListener('success', (event) => {
    const { instanceId } = event.detail;
    console.log('Card revealed successfully', instanceId);
  });
</script>

​
Failure Event

Dispatched when the card reveal API call fails.
PropertyTypeDescription
errorstringHuman-readable error message
instanceIdstringUnique ID for this widget instance
<script>
  document.getElementById('reveal-widget').addEventListener('failure', (event) => {
    const { error } = event.detail;
    console.error('Card reveal failed:', error);
    // Show error UI to user
  });
</script>

​
Copy Event

Dispatched when a user copies a card field value (card number, security code, or expiration) to the clipboard using the copy buttons inside the widget. The actual clipboard operation happens within the secure iframe — no PCI data is exposed in the event.
PropertyTypeDescription
instanceIdstringUnique ID for this widget instance
<script>
  document.getElementById('reveal-widget').addEventListener('copy', (event) => {
    const { instanceId } = event.detail;
    console.log('Field copied to clipboard', instanceId);
  });
</script>

​
Public Methods

The widget exposes methods for programmatic control. These are useful when you want to control the reveal behavior externally instead of using the built-in toggle.
MethodDescription
requestCardReveal()Trigger the card reveal API call
toggleCardSide()Flip between front and back views
setCardSide(side)Set card side to "front" or "back"
refresh()Reset state and re-fetch card details
<reveal-card
  id="reveal-widget"
  token="your-token"
  env="production"
></reveal-card>

<button onclick="document.getElementById('reveal-widget').requestCardReveal()">
  Reveal Card
</button>

<button onclick="document.getElementById('reveal-widget').toggleCardSide()">
  Flip Card
</button>

​
Complete Example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Card Reveal</title>
    <script
      type="module"
      src="https://assets.synctera.com/widgets/reveal-card/v1.1.1/index.js"
    ></script>
  </head>
  <body>
    <h1>Your Card</h1>

    <div id="error-message" style="color: red; display: none;"></div>

    <reveal-card
      id="reveal-widget"
      env="production"
      card-side="front"
      last-four="1234"
      emboss-name="Jane Doe"
      emboss-name-two="Acme Corp"
      card-network="visa"
      card-type="DEBIT"
      show-toggle
    ></reveal-card>

    <script>
      async function initializeWidget() {
        try {
          const response = await fetch('/api/card-widget-token', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              card_id: 'your-card-id',
              widget_type: 'REVEAL'
            })
          });

          const { widget_token } = await response.json();

          const widget = document.getElementById('reveal-widget');
          widget.setAttribute('token', widget_token);

          widget.addEventListener('load', (event) => {
            console.log('Widget ready:', event.detail.instanceId);
          });

          widget.addEventListener('error', (event) => {
            const { error, failedFields } = event.detail;
            console.error('Widget failed to initialize:', error, failedFields);
            document.getElementById('error-message').textContent = error;
            document.getElementById('error-message').style.display = 'block';
          });

          widget.addEventListener('success', (event) => {
            console.log('Card revealed:', event.detail);
          });

          widget.addEventListener('failure', (event) => {
            document.getElementById('error-message').textContent = event.detail.error;
            document.getElementById('error-message').style.display = 'block';
          });

        } catch (error) {
          console.error('Failed to initialize widget:', error);
        }
      }

      window.addEventListener('DOMContentLoaded', initializeWidget);
    </script>
  </body>
</html>

​
Migration from card-reveal-widget

The Reveal Card widget was previously named <card-reveal-widget>. It has been renamed to <reveal-card> for consistency with the other Synctera widgets (<activate-card>, <set-pin>).

​
What changed

  1. CDN URL: The script URL changed from widgets/card-reveal/v1.0.0/index.js to widgets/reveal-card/v1.1.1/index.js
  2. Element name: The custom element changed from <card-reveal-widget> to <reveal-card>
  3. Existing public methods and events are unchanged (requestCardReveal(), toggleCardSide(), setCardSide(), refresh(), success, failure, copy)
  4. New initialization events: <reveal-card> adds load and error events (plus matching onLoad / onError callback properties) so you can react to the widget becoming ready or failing to initialize — see Event Handling. These events are additive and existing integrations continue to work without changes.

​
Backwards compatibility

The new widget script registers both <reveal-card> (recommended) and <card-reveal-widget> (deprecated alias). If you load the new CDN URL, your existing <card-reveal-widget> elements will continue to work, but a deprecation warning will be logged to the browser console.

​
Migration steps

  1. Update the script tag to use the new CDN URL
  2. Replace <card-reveal-widget> with <reveal-card> in your HTML
  3. Update any document.querySelector('card-reveal-widget') or document.createElement('card-reveal-widget') calls
The old CDN URL (widgets/card-reveal/v1.0.0/index.js) is frozen and will not receive updates. Switch to the new URL to receive future improvements and fixes.