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.0/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 card reveal outcomes:
  • success — Card details retrieved successfully.
  • failure — Card reveal failed (API error, timeout, etc.).
  • copy — A card field value was copied to the clipboard.

​
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.0/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('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.0/index.js
  2. Element name: The custom element changed from <card-reveal-widget> to <reveal-card>
  3. All public methods and events remain the same (requestCardReveal(), toggleCardSide(), setCardSide(), refresh(), success, failure, copy)

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