Reveal Card Widget

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>.

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>

import { useEffect } from 'react';

function RevealCard({ widgetToken }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://assets.synctera.com/widgets/reveal-card/v1.1.1/index.js';
    document.head.appendChild(script);

    return () => {
      document.head.removeChild(script);
    };
  }, []);

  return (
    <reveal-card
      token={widgetToken}
      env="production"
    />
  );
}

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"

const response = await fetch(
  `https://api.synctera.com/v2/cards/${cardId}/widget_token?widget_type=REVEAL`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  }
);

const { widget_token } = await response.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.

Add the <reveal-card> web component to your page:

<reveal-card
  token="your-widget-token"
  env="production"
></reveal-card>

Configuration Options

Property	Type	Required	Default	Description
`token`	`string`	Yes	-	Widget token obtained from the API
`env`	`string`	Yes	-	Environment: `sandbox` or `production`
`theme`	`string`	No	`"default"`	Theme preset: `"default"` or `"night-shift"`
`styles`	`string`	No	`{}`	JSON string of design tokens for visual customization
`card-side`	`string`	No	`"front"`	Which side to show initially: `"front"` or `"back"`
`card-form`	`string`	No	`"physical"`	Card form factor: `"physical"` or `"virtual"`
`card-type`	`string`	No	`""`	Card type label displayed on the card (e.g., `"DEBIT"`, `"CREDIT"`)
`last-four`	`string`	No	`""`	Last 4 digits of PAN, shown on the card front
`emboss-name`	`string`	No	`""`	Cardholder name displayed on the card front (line 1)
`emboss-name-two`	`string`	No	`""`	Optional second emboss line displayed below the cardholder name in a smaller font (e.g., business name)
`card-network`	`string`	No	`"visa"`	Card network: `"visa"` or `"mastercard"`
`show-toggle`	`boolean`	No	`false`	Renders a built-in toggle to reveal/hide card details
`toggle-label`	`string`	No	`""`	Custom label text for the built-in toggle
`custom-labels`	`string`	No	`"{}"`	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>

<reveal-card
  token="your-token"
  env="production"
  card-side="back"
></reveal-card>

<reveal-card
  token="your-token"
  env="production"
  card-form="virtual"
  card-type="DEBIT"
></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:

Event	`addEventListener`	Callback property
Initialization success	`widget.addEventListener('load', fn)`	`widget.onLoad = fn`
Initialization failure	`widget.addEventListener('error', fn)`	`widget.onError = fn`
Reveal success	`widget.addEventListener('success', fn)`	`widget.onSuccess = fn`
Reveal failure	`widget.addEventListener('failure', fn)`	`widget.onFailure = fn`
Field copied to clipboard	`widget.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.

Property	Type	Description
`instanceId`	`string`	Unique 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.

Property	Type	Description
`error`	`string`	Human-readable error message (safe to display to end users)
`failedFields`	`string[]`	Logical surfaces that failed to initialize. The Reveal Card widget has a single display surface, so this is always `['display-controller']`.
`instanceId`	`string`	Unique 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.

Property	Type	Description
`instanceId`	`string`	Unique 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.

Property	Type	Description
`error`	`string`	Human-readable error message
`instanceId`	`string`	Unique 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.

Property	Type	Description
`instanceId`	`string`	Unique 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.

Method	Description
`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>

import { useEffect, useState, useRef } from 'react';

function RevealCardView({ cardId }) {
  const [widgetToken, setWidgetToken] = useState(null);
  const [error, setError] = useState(null);
  const widgetRef = useRef(null);

  useEffect(() => {
    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://assets.synctera.com/widgets/reveal-card/v1.1.1/index.js';
    document.head.appendChild(script);

    fetch('/api/card-widget-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ card_id: cardId, widget_type: 'REVEAL' })
    })
      .then(res => res.json())
      .then(data => setWidgetToken(data.widget_token))
      .catch(err => setError(err.message));

    return () => {
      document.head.removeChild(script);
    };
  }, [cardId]);

  useEffect(() => {
    if (!widgetToken || !widgetRef.current) return;

    const handleLoad = (event) => {
      console.log('Widget ready:', event.detail.instanceId);
    };

    const handleError = (event) => {
      const { error: initError, failedFields } = event.detail;
      console.error('Widget failed to initialize:', initError, failedFields);
      setError(initError);
    };

    const handleSuccess = (event) => {
      console.log('Card revealed:', event.detail);
    };

    const handleFailure = (event) => {
      setError(event.detail.error);
    };

    const widget = widgetRef.current;
    widget.addEventListener('load', handleLoad);
    widget.addEventListener('error', handleError);
    widget.addEventListener('success', handleSuccess);
    widget.addEventListener('failure', handleFailure);

    return () => {
      widget.removeEventListener('load', handleLoad);
      widget.removeEventListener('error', handleError);
      widget.removeEventListener('success', handleSuccess);
      widget.removeEventListener('failure', handleFailure);
    };
  }, [widgetToken]);

  if (error) return <div style={{ color: 'red' }}>Error: {error}</div>;
  if (!widgetToken) return <div>Loading...</div>;

  return (
    <reveal-card
      ref={widgetRef}
      token={widgetToken}
      env="production"
      card-side="front"
      last-four="1234"
      emboss-name="Jane Doe"
      emboss-name-two="Acme Corp"
      card-network="visa"
      show-toggle
    />
  );
}

export default RevealCardView;

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

CDN URL: The script URL changed from widgets/card-reveal/v1.0.0/index.js to widgets/reveal-card/v1.1.1/index.js
Element name: The custom element changed from <card-reveal-widget> to <reveal-card>
Existing public methods and events are unchanged (requestCardReveal(), toggleCardSide(), setCardSide(), refresh(), success, failure, copy)
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

Update the script tag to use the new CDN URL
Replace <card-reveal-widget> with <reveal-card> in your HTML
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.

Overview

Products

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Validate a Value Proposition

Reveal Card Widget

Step 1: Load the Widget Script

Step 2: Get a Widget Token

Step 3: Add the Widget Component

Configuration Options

Card Side and Form

Built-in Toggle

Custom Labels

Event Handling

Load Event

Error Event

Success Event

Failure Event

Copy Event

Public Methods

Complete Example

Migration from card-reveal-widget

What changed

Backwards compatibility

Migration steps

​Step 1: Load the Widget Script

​Step 2: Get a Widget Token

​Step 3: Add the Widget Component

​Configuration Options

​Card Side and Form

​Built-in Toggle

​Custom Labels

​Event Handling

​Load Event

​Error Event

​Success Event

​Failure Event

​Copy Event

​Public Methods

​Complete Example

​Migration from card-reveal-widget

​What changed

​Backwards compatibility

​Migration steps

Step 1: Load the Widget Script

Step 2: Get a Widget Token

Step 3: Add the Widget Component

Configuration Options

Card Side and Form

Built-in Toggle

Custom Labels

Event Handling

Load Event

Error Event

Success Event

Failure Event

Copy Event

Public Methods

Complete Example

Migration from card-reveal-widget

What changed

Backwards compatibility

Migration steps