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.
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/card-reveal/v1.0.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 a set period and are scoped to a specific card. Generate a new token on each page load or when needed.

​
Step 3: Add the Widget Component

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

​
Configuration Options

PropertyTypeRequiredDefaultDescription
tokenstringYes-Widget token obtained from the API
envstringYes-Environment: sandbox or production
themestringNo"default"Theme style: "default" or "night-shift"
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
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: 
<card-reveal-widget
  token="your-token"
  env="production"
  card-side="front"
  last-four="1234"
  emboss-name="Jane Doe"
  card-type="DEBIT"
  card-network="visa"
></card-reveal-widget>

​
Built-in Toggle

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

​
Custom Labels

Customize the labels displayed in the widget: 
<card-reveal-widget
  token="your-token"
  env="production"
  custom-labels='{
    "panLabel": "Card Number",
    "cvvLabel": "Security Code",
    "expiryLabel": "Expires",
    "retryButtonText": "Retry",
    "toggleLabel": "Show Card Details",
    "cardholderPlaceholder": "CARDHOLDER"
  }'
></card-reveal-widget>
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.).

​
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
<card-reveal-widget id="reveal-widget" token="your-token" env="production"></card-reveal-widget>
<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>

​
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
<card-reveal-widget
  id="reveal-widget"
  token="your-token"
  env="production"
></card-reveal-widget>

<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/card-reveal/v1.0.0/index.js"
    ></script>
  </head>
  <body>
    <h1>Your Card</h1>

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

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

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