Overview

To enable an instant payment (PULL/PUSH) with an external card-on-file, the following steps are required:

Add card-on-file
- Using the External Card Creation Widget
  - This step is required if you are not PCI certified
- Using API
  - You can use this option if you are PCI certified
For PULL payments, enable 3-D Secure (3DS) authentication
Initiate external card-on-file payment

This step is required if you are not PCI certified. The External Card Creation Widget allows your customers to securely enter payment card information directly in your application. Since the widget communicates directly between the client and Synctera, it removes the need for you to be PCI certified. The information is stored securely and can be retrieved via Synctera API.

The External Card Creation Widget provides a complete, secure payment form that includes:

Card Number (PAN) - Primary account number with automatic formatting
Cardholder Name - Name on the card
Expiration Date - Card expiry with MM/YY format
CVV/CVC - Security code (3-4 digits)
Billing Address - Optional billing address fields

All sensitive card data is handled in isolated iframes, ensuring PCI compliance while giving you full control over the user experience.

Getting Started

Prerequisites

Before integrating the widget, ensure you have:

Synctera API Keys - Working API keys for your business
Widget Token - A widget token for tokenizing cards (obtained from the API)
Environment Configuration - Know which environment you’re using (sandbox, or production)

API Keys

First, ensure you have your Synctera API Keys working for your business. You’ll need these to obtain widget tokens.

Mobile Applications

If you’re integrating the widgets in a mobile application, you may need to use one of the following web views:

WKWebView in an iOS application
WebView in an Android application
WebView in React Native

Basic Integration

Load the External Card Creation widget script into your page by adding the following script tag to the bottom of the body of your HTML:

    <script 
      type="module" 
      src="https://assets.synctera.com/widgets/external-card-creation/v1.0.0/index.js">
    </script>

Request a widget token for tokenizing cards from your backend using the Synctera API. The widget token is required for the widget to authenticate and submit card data.

curl -X POST "https://api-sandbox.synctera.com/v1/external_cards/widget_token?widget_type=TOKENIZE&customer_id={customerId}" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json"

Widget tokens expire after a set period and are scoped to a specific customer. Generate a new token on each page load or when needed. Widget tokens are one use only, so if a user submits and gets an error that invalidates the token and the widget will be to be supplied a new token.

Add the <external-card-creation> web component to your page where you want the card form to appear:

<body>
  <external-card-creation
    token="your-widget-token"
    env="sandbox"
  ></external-card-creation>
</body>

Configuration Options

The <external-card-creation> component supports the following 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 style: `"default"` or `"night-shift"`
`include-address`	`boolean`	No	`false`	Show/hide billing address fields section
`custom-labels`	`string`	No	`{}`	JSON string of custom labels for form fields

Environment Configuration

The env property determines which API endpoint the widget uses:

sandbox - Sandbox/test environment (recommended for testing)
production - Production environment

Always use sandbox for testing and development. Only use production for live integrations.

Theme Options

The widget supports two themes:

<external-card-creation
  token="your-token"
  env="sandbox"
  theme="default"
></external-card-creation>

Custom Labels

Customize the labels and text displayed in the widget by passing a JSON string to the custom-labels attribute:

<external-card-creation
  token="your-token"
  env="sandbox"
  custom-labels='{
    "widgetTitle": "Payment Information",
    "cardNameLabel": "Full Name on Card",
    "cardNumberLabel": "Card Number",
    "expirationDateLabel": "Expiry",
    "securityCodeLabel": "CVV",
    "streetAddressLabel": "Street Address",
    "cityLabel": "City",
    "stateLabel": "State",
    "zipCodeLabel": "ZIP Code",
    "submitButtonText": "Add Payment Method",
    "submitLoadingText": "Processing...",
    "useAddressOnFileLabel": "Use my saved address"
  }'
></external-card-creation>

Available custom label keys:

widgetTitle - Widget header text
cardNameLabel - Name on card label
cardNamePlaceholder - Name on card placeholder
cardNumberLabel - Card number label
cardPanPlaceholder - Card number placeholder
expirationDateLabel - Expiration date label
cardExpPlaceholder - Expiration date placeholder
securityCodeLabel - CVV/CVC label
cardCvvPlaceholder - CVV placeholder
streetAddressLabel - Street address label
addressLine1Placeholder - Street address placeholder
addressLine2Label - Address line 2 label
addressLine2Placeholder - Address line 2 placeholder
cityLabel - City label
addressCityPlaceholder - City placeholder
stateLabel - State label
addressStatePlaceholder - State placeholder
zipCodeLabel - ZIP code label
addressZipPlaceholder - ZIP code placeholder
submitButtonText - Submit button text
submitLoadingText - Loading state text
useAddressOnFileLabel - Address checkbox label
billingAddressTitle - Billing address section title

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 tokenization completed successfully.
failure — Card tokenization 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.

Property	Type	Description
`instanceId`	`string`	Unique ID for this widget instance

<external-card-creation id="card-widget" token="your-token" env="sandbox"></external-card-creation>
<script>
  document.getElementById('card-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.

Property	Type	Description
`instanceId`	`string`	Unique ID for this widget instance
`error`	`string`	Human-readable error message (safe to display)
`failedFields`	`string[]`	List of field types that failed to load

<script>
  document.getElementById('card-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 Event

The widget dispatches a success event when card tokenization is successful. The event detail contains external_card_id and message (sensitive card data is not returned):

<external-card-creation
  id="card-widget"
  token="your-token"
  env="sandbox"
></external-card-creation>

<script>
  document.getElementById('card-widget').addEventListener('success', (event) => {
    console.log('Card tokenized successfully:', event.detail);
    const { external_card_id, message } = event.detail;
    // Use external_card_id for payments or to retrieve card via API
  });
</script>

Failure Event

The widget dispatches a failure event when card tokenization fails:

widget.addEventListener('failure', (event) => {
  const { error } = event.detail;
  console.error('Tokenization failed:', error);
  // Display error message to user
});

Callback Properties (JavaScript Only)

As an alternative to addEventListener, you can set callback functions directly on the element via JavaScript. These are JS-only properties and cannot be set as HTML attributes.

const widget = document.getElementById('card-widget');

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

widget.onError = (event) => {
  console.error('Widget failed:', event.detail.error);
};

widget.onSuccess = (event) => {
  console.log('Card tokenized:', event.detail.external_card_id);
};

widget.onFailure = (event) => {
  console.error('Tokenization failed:', event.detail.error);
};

Complete Example

Here’s a complete example showing a full integration with widget token fetching and error handling:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>External Card Creation Widget Example</title>
    <script 
      type="module" 
      src="https://assets.synctera.com/widgets/external-card-creation/v1.0.0/index.js">
    </script>
  </head>
  <body>
    <h1>Add Payment Card</h1>
    
    <div id="error-message" style="color: red; display: none;"></div>
    
    <external-card-creation
      id="card-widget"
      env="sandbox"
    ></external-card-creation>
    
    <script>
      async function initializeWidget() {
        try {
          // Fetch widget token from your backend
          const response = await fetch('/api/widget-token', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              customer_id: 'your-customer-id'
            })
          });
          
          const { widget_token } = await response.json();
          
          // Set token on widget
          const widget = document.getElementById('card-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) => {
            const { external_card_id } = event.detail;
            console.log('Card tokenized:', external_card_id);
            alert('Card added successfully!');
            // Use external_card_id for payments or redirect
          });
          
          widget.addEventListener('failure', (event) => {
            const errorDiv = document.getElementById('error-message');
            errorDiv.textContent = event.detail.error;
            errorDiv.style.display = 'block';
          });
          
        } catch (error) {
          console.error('Failed to initialize widget:', error);
          document.getElementById('error-message').textContent = 
            'Failed to load payment form. Please refresh the page.';
          document.getElementById('error-message').style.display = 'block';
        }
      }
      
      // Initialize when page loads
      window.addEventListener('DOMContentLoaded', initializeWidget);
    </script>
  </body>
</html>

Address Fields

The widget supports optional billing address collection. Enable address fields by setting include-address="true":

<external-card-creation
  token="your-token"
  env="sandbox"
  include-address="true"
></external-card-creation>

When address fields are enabled, the widget includes:

Street Address (Address Line 1)
Address Line 2 (optional)
City
State
ZIP Code

The widget also provides a checkbox option to “Use address on file” which will hide the address fields if checked.

Field Validation

The widget automatically validates all card fields in real-time:

Card Number (PAN): Validates card number format and runs Luhn algorithm check
Cardholder Name: Validates alphabetical characters and proper formatting
Expiration Date: Validates MM/YY format and ensures date is not expired
CVV/CVC: Validates 3-4 digit security code
Address Fields: Validates address format, state codes, and ZIP codes

The submit button is automatically disabled until all required fields are valid.

Card verifications

For security purposes, a number of verifications are performed when the card is added. For details, see the Verifications section.

Security & PCI Compliance

All sensitive card data is handled in isolated iframes, ensuring that your application never touches PCI-sensitive information.

Security Features

Iframe Isolation: Each field runs in its own sandboxed iframe
No Data Exposure: Sensitive data never touches the parent page
Token-based Authentication: Secure API communication using widget tokens
Origin Validation: All messages validated against expected origins
XSS Protection: All input is sanitized and validated

PCI Compliance

The widget is designed to help you maintain PCI compliance:

Sensitive card data is isolated in secure iframes
Your application never handles raw card data
All communication uses secure, tokenized endpoints
The widget handles PCI compliance requirements on your behalf

Troubleshooting

If the widget doesn’t appear on your page:

Check Script Loading: Ensure the widget script is loaded before the component is used
Check Token: Verify the widget token is valid and not expired
Check Environment: Ensure the env attribute matches your API environment
Check Console: Look for JavaScript errors in the browser console

Tokenization Failing

If card submission fails:

Verify Token: Ensure the widget token is valid and not expired
Check Environment: Ensure the env matches your API endpoint
Check Network: Inspect network requests in browser DevTools
Review Error Events: Listen to the failure event for detailed error messages

Additional Information

Supported Browsers

The widget supports all modern browsers:

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Responsive Design

The widget is fully responsive and adapts to mobile and desktop screens automatically.

Custom Styling

The widget comes with a theme option and labels can be passed in as attributes

Add card-on-file using API

If you are PCI certified, you have the option to create the External Card directly using the card credentials by calling POST /v1/external_cards. In addition to the card credentials (pan and expiration_month/expiration_year), you must provide the customer_id and cardholder name (business_id may optionally be provided if applicable). cvv is optional (for migration purposes), but should be provided for adding new cards as it provides an additional layer of security and reduces the risk of fraud. A billing_address can be added optionally, if it is different from the cardholder’s address-on-file on the Synctera platform. For more details on CVV and address verification, see the Verifications section.

Example request/response

Example request:

curl \
  $baseurl/v1/external_cards \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  -d '
  {
    "pan": "4005519200000004",
    "cvv": "123",
    "expiration_month": "04",
    "expiration_year": "26",
    "name": "Jane Taylor",
    "customer_id": "{CUSTOMER_ID}"
  }'

Example response:

{
  "created_time": "2023-01-18T12:03:46.892809-05:00",
  "currency": "USD",
  "customer_id": "{CUSTOMER_ID}",
  "expiration_month": "4",
  "expiration_year": "2026",
  "id": "{EXTERNAL_CARD_ID}",
  "last_four": "0004",
  "last_modified_time": "2023-01-18T12:03:46.892809-05:00",
  "name": "Jane Taylor",
  "verifications": {
    "address_verification_result": "VERIFIED",
    "cvv2_result": "VERIFIED",
    "pull_enabled": true,
    "push_enabled": true,
    "state": "SUCCEEDED"
  }
}

Verifications

When an External Card is created, the following verifications are performed:

CVV2 verification:
- CVV2 provided in the widget or in the API is validated against the CVV2 on file with the issuer
Address verification:
- Unless billing address is specified in the widget/API, the address stored on the customer’s record on Synctera is validated against the address-on-file with the issuer
- Note that if business_id is provided, address verification is performed on the Business’s legal address, otherwise, it is performed on the Person’s legal address. However, cardholder name matching is performed on the Person’s name regardless.
Name verification:
- Name provided in the widget is validated against the name on file with the issuer

The verification results are displayed in the verifications object. In addition to CVV2, address and name, the verifications object contains information about the card, as well as the type of transactions the card supports. If either pull_enabled or push_enabled are false, that type of transaction may not be performed using the card.

Enable 3DS and create payment

Once a card has been added on file, a PULL or a PUSH payment can be initiated with the card. For PULL payments, 3-D Secure (3DS) authentication is required. For details on how to enable 3DS, and how to iniate a payment with a card-on-file, see the Instant Payments - Card-On-File section.

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

​Overview

​Add card-on-file using the External Card Creation Widget

​Getting Started

​Prerequisites

​API Keys

​Mobile Applications

​Basic Integration

​Step 1: Load the Widget Script

​Step 2: Get a Widget Token

​Step 3: Add the Widget Component

​Configuration Options

​Environment Configuration

​Theme Options

​Custom Labels

​Event Handling

​Load Event

​Error Event

​Success Event

​Failure Event

​Callback Properties (JavaScript Only)

​Complete Example

​Address Fields

​Field Validation

​Card verifications

​Security & PCI Compliance

​Security Features

​PCI Compliance

​Troubleshooting

​Widget Not Loading

​Tokenization Failing

​Additional Information

​Supported Browsers

​Responsive Design

​Custom Styling

​Add card-on-file using API

​Example request/response

​Verifications

​Enable 3DS and create payment

Overview

Add card-on-file using the External Card Creation Widget

Getting Started

Prerequisites

API Keys

Mobile Applications

Basic Integration

Step 1: Load the Widget Script

Step 2: Get a Widget Token

Step 3: Add the Widget Component

Configuration Options

Environment Configuration

Theme Options

Custom Labels

Event Handling

Load Event

Error Event

Success Event

Failure Event

Callback Properties (JavaScript Only)

Complete Example

Address Fields

Field Validation

Card verifications

Security & PCI Compliance

Security Features

PCI Compliance

Troubleshooting

Widget Not Loading

Tokenization Failing

Additional Information

Supported Browsers

Responsive Design

Custom Styling

Add card-on-file using API

Example request/response

Verifications

Enable 3DS and create payment