Skip to main content
The Activate Card widget allows your customers to activate their physical card by entering the card number (PAN) and security code (CVV).
Activate Card

​
Step 1: Load the Widget Script

Load the Activate Card widget script into your page by adding the following script tag: 
<script
  type="module"
  src="https://assets.synctera.com/widgets/activate/v1.0.1/index.js"
></script>

​
Step 2: Get a Widget Token

Request a widget token from your backend using the Synctera API. The widget token is required for the widget to authenticate and submit data. 
curl -X POST "https://api.synctera.com/v1/cards/{card_id}/widget_token?widget_type=ACTIVATE" \
  -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 <activate-card> web component to your page: 
<activate-card
  token="your-widget-token"
  env="production"
></activate-card>

​
Configuration Options

PropertyTypeRequiredDefaultDescription
tokenstringYes-Widget token obtained from the API
envstringYes-Environment: sandbox or production
themestringNo"default"Theme style: "default" or "night-shift"
custom-labelsstringNo{}JSON string of custom labels for form fields

​
Custom Labels

Customize the labels displayed in the widget: 
<activate-card
  token="your-token"
  env="production"
  custom-labels='{
    "widgetTitle": "Activate Your New Card",
    "cardNumberLabel": "Card Number (PAN)",
    "securityCodeLabel": "Security Code",
    "submitButtonText": "Activate Now",
    "submitLoadingText": "Processing..."
  }'
></activate-card>
Available custom label keys:
  • widgetTitle - Widget header text
  • cardNumberLabel - Card number field label
  • securityCodeLabel - CVV field label
  • cardPanPlaceholder - Card number placeholder
  • cardCvvPlaceholder - CVV placeholder
  • submitButtonText - Submit button text
  • submitLoadingText - Loading state text

​
Event Handling

The widget dispatches lifecycle events for initialization and action outcomes:
  • load — Widget initialized successfully, all fields are ready for user input.
  • error — Widget failed to initialize (field load failure, network error, or timeout).
  • success — Card activation completed successfully.
  • failure — Card activation failed (API error, validation error, etc.).

​
Load Event

Dispatched when all secure input fields have loaded and the widget is fully functional. Use it to hide loading UI or enable dependent controls.
PropertyTypeDescription
instanceIdstringUnique ID for this widget instance
<activate-card id="activate-widget" token="your-token" env="production"></activate-card>
<script>
  document.getElementById('activate-widget').addEventListener('load', (event) => {
    const { instanceId } = event.detail;
    console.log('Widget ready', instanceId);
  });
</script>

​
Error Event

Dispatched when the widget fails to initialize. This means one or more secure input fields could not load, and the widget is not functional. Show an error message or retry UI to the user.
PropertyTypeDescription
instanceIdstringUnique ID for this widget instance
errorstringHuman-readable error message (safe to display)
failedFieldsstring[]List of field types that failed to load
<script>
  document.getElementById('activate-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>
The load and error events are mutually exclusive — exactly one will fire during widget initialization. Always listen for both to handle all scenarios.

​
Success and Failure Events

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

<script>
  const widget = document.getElementById('activate-widget');

  widget.addEventListener('success', (event) => {
    console.log('Card activated successfully:', event.detail);
    // Handle success - redirect or update UI
  });

  widget.addEventListener('failure', (event) => {
    console.error('Activation failed:', event.detail);
    // Handle error - display message to user
  });
</script>

​
Complete Example

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

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

    <activate-card
      id="activate-widget"
      env="production"
    ></activate-card>

    <script>
      async function initializeWidget() {
        try {
          // Fetch widget token from your backend
          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: 'ACTIVATE'
            })
          });

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

          // Set token on widget
          const widget = document.getElementById('activate-widget');
          widget.setAttribute('token', widget_token);

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

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

          widget.addEventListener('success', (event) => {
            console.log('Card activated:', event.detail);
            alert('Card activated successfully!');
          });

          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>