Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synctera.com/llms.txt

Use this file to discover all available pages before exploring further.

Marqeta is sunsetting their Marqeta.js widget library. For new integrations, use Synctera Widgets.For migration guidance, see the Migration Guide.
Through the marqeta.js client library, you can display the following pieces of sensitive card information for a customer inside your application:
  • PAN (Primary Account Number)
  • CVV (Card Verification Value)
  • EXP (Expiration Date)
  • PIN (Personal Identification Number - v2.0.0+)
Through the Activate Card and Set PIN Widgets, you can interact with your card to activate it or to set card’s PIN:
  • Activate Card (activates a physical card by entering in the card number and CVV)
  • Set PIN (sets the Card PIN for a newly activated card)

​
Display Card PAN, CVV, and EXP

Refer to Marqeta’s guide Using Marqeta.js for additional information on the widget configuration and styling.
The steps below describe how the application uses a client access token to show PAN, CVV and Card EXP using the marqeta.js client library:

​
Step 1: Load marqeta.js

Load marqeta.js into the window object of the browser by adding the following script into the <head> tag of the required page: 
<script
  src="https://widgets.marqeta.com/marqetajs/2.0.0/marqeta.min.js"
  type="text/javascript"
></script>

​
Step 2: Get a Client Access Token

Request a client access token for a card from Synctera via the POST request for /cards/{card_id}/client_token endpoint. Pass clientAccessToken to your front-end via SSR or HTTP request. This token expires after five minutes and is only applicable to the given card, so it’s a good idea to create a client access token on every page load: 
curl -X POST "https://api-sandbox.synctera.com/v0/cards/{cardId}/client_token" \
  -H "Content-Length: 0" \
  -H "Authorization: Bearer {apiKey}"

# Response: {"client_token": ... }

​
Step 3: Add HTML Elements

Add a separate HTML div element to your client page per each piece of the sensitive card data (Card PAN, Card CVV, Card EXP). You can attach this information to any HTML container: 
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Synctera</title>
    <script
      src="https://widgets.marqeta.com/marqetajs/2.0.0/marqeta.min.js"
      type="text/javascript"
    ></script>
  </head>
  <body>
    <!-- each piece of sensitive information must have its own div -->
    <div id="display-card-pan"></div>
    <div id="display-card-cvv"></div>
    <div id="display-card-exp"></div>
  </body>
</html>

​
Step 4: Initialize marqeta.js

Initialize marqeta.js via bootstrap with token by calling window.marqeta.bootstrap. It will create an HTML iframe element inside each HTML div element. You can style the div elements and inner contents for the card PAN, card CVV, card EXP containers. To do so, use the showPan object as described in Using Marqeta.js > The showPan object: 
window.marqeta.bootstrap({
  clientAccessToken: clientAccessToken,
  integrationType: "custom",
  component: {
    showPan: {
      cardPan: { domId: "display-card-pan", format: true },
      cardExp: { domId: "display-card-exp", format: true },
      cardCvv: { domId: "display-card-cvv" },
    },
  },
  callbackEvents: {
    onSuccess: () => console.log("Widget loaded!"),
    onFailure: () => console.warn("Widget failed to load."),
  },
});

​
Sequence Diagram

​
Display Card PIN

Loading the PIN must be done in its own call to window.marqeta.bootstrap, however you may call two instances simultaneously.

​
Step 1: Load marqeta.js and Get Token

Follow the first two steps from Display Card PAN, CVV, and EXP.

​
Step 2: Add HTML Elements

Add separate HTML elements to your client page for the card PIN. You can attach this information to any HTML container: 
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Synctera</title>
    <script
      src="https://widgets.marqeta.com/marqetajs/2.0.0/marqeta.min.js"
      type="text/javascript"
    ></script>
  </head>
  <body>
    <!-- PIN provides three different features -->
    <span>
      <div id="display-card-pin"></div>
      <button id='toggle-card-pin'>Toggle</button>
      <div id='pin-timeout'></div>
    </span>
  </body>
</html>

​
Step 3: Initialize marqeta.js for PIN

Initialize marqeta.js via bootstrap with token by calling window.marqeta.bootstrap. It will create an HTML iframe element inside each HTML element. You can style the elements and inner contents for the card PIN containers. To do so, use the pinReveal object as described in Using Marqeta.js > The pinReveal object: 
window.marqeta.bootstrap({
  clientAccessToken: clientAccessToken,
  integrationType: "custom",
  component: {
    pinReveal: {
      cardPin: { domId: "display-card-pin" },
      toggleCardPin: { domId: "toggle-card-pin", mode: "transparent" },
      hidePinTimeout: {
        domId: "pin-timeout",
        hideTimeout: 10, // A value between 5 and 15
        styles: {}, // Requires styles object, can be empty
      },
    },
  },
  callbackEvents: {
    onSuccess: () => console.log("Widget loaded!"),
    onFailure: () => console.warn("Widget failed to load."),
  },
});

​
Activate Card and Set PIN Widgets

For new integrations, use the Synctera Activate Card Widget and Synctera Set PIN Widget instead.
The Activate Card widget and Set PIN widget are displayed inside HTML iframe elements, with source URLs provided by the /cards/card_widget_url route.
Refer to Marqeta’s guide Using Activate Card and Set PIN Widgets for additional information.

​
Step 1: Fetch the Widget URL

On the server, make a request to /cards/card_widget_url. For the Activate Card widget (widget_type === ‘activate_card’), you can omit the card_id param in the query: 
curl -X GET "https://api-sandbox.synctera.com/v0/cards/card_widget_url?card_id={cardId}&customer_id={customerId}&account_id={accountId}&widget_type={widgetType}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {apiKey}"

# Response: {"url": ... }

​
Step 2: Embed the Widget

Pass the acquired URL to your front-end via SSR or HTTP request. Include the URL into an iframe on your client page. The desired widget will be rendered inside the iframe, allowing the user to input either card PAN or card PIN and press submit: 
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Synctera</title>
  </head>
  <body>
    <iframe
      src="{cardWidgetUrl}"
      title="Card Widget"
    />
  </body>
</html>

​
Sequence Diagram

​
Upgrading from Marqeta 1.1.0 to 2.0.0

To take advantage of the PIN reveal feature, you will need to upgrade from Marqeta 1.1.0 to 2.0.0. If you already implemented the Marqeta widget, read this section to quickly upgrade.
  1. Replace https://widgets.marqeta.com/marqetajs/1.1.0/marqeta.min.js with https://widgets.marqeta.com/marqetajs/2.0.0/marqeta.min.js
  2. For the config passed to window.marqeta.bootstrap({ .... }), the “showPan” field needs to wrapped in a “component” field: 
window.marqeta.bootstrap({
  // ...other config
  component: {
    showPan: {
      cardPan: { domId: "display-card-pan", format: true },
      cardExp: { domId: "display-card-exp", format: true },
      cardCvv: { domId: "display-card-cvv" },
    },
  },
  // ...other config
});
That’s it!

​
Styling and Customization

As of version 2.0.0 of the Marqeta library allows for some customization of the fields’ appearances, including the css hover state. Supported CSS attributes generally include: color, font-family, font-size, background, font-weight and letter-spacing. For the particulars on styling, please review the Using Marqeta.js > Concepts
From Marqeta’s documentation: “CSS importing schemes such as @import and @url are not supported. Marqeta.js only supports web-safe/system fonts that can be displayed on modern web browsers without a specific download.”

​
TypeScript Types

We use Typescript at Synctera and find it helpful to type our window properties. See the example typescript below for the window.marqeta version 2.0.0 object provided by marqeta.js: 
// global.d.ts
declare interface Window {
   marqeta: {
     bootstrap(params: MarqetaShowPanParams | MarqetaPinRevealParams): void;
   }
}

// marqeta.d.ts
interface MarqetaBaseParams {
  clientAccessToken: string;
  options?: {
     // Must be included if using PIN reveal
    cardholderVerificationMethod: 'OTHER';
  };
  integrationType: 'custom';
  callbackEvents?: {
    onSuccess?: () => void;
    onFailure: () => void;
  };
}

export interface MarqetaShowPanParams extends MarqetaBaseParams {
  component: {
    showPan: {
      cardPan?: MarqetaShowItem;
      cardExp?: MarqetaShowItem;
      cardCvv?: Omit<MarqetaShowItem, 'format'>;
    };
    pinReveal?: undefined;
  };
}

export interface MarqetaPinRevealParams extends MarqetaBaseParams {
  component: {
    showPan?: undefined;
    pinReveal: {
      cardPin: Omit<MarqetaShowItem, 'format'>;
      toggleCardPin?: {
        domId: string;
        mode: 'transparent';
        onRevealSuccess?: () => void;
        onHideSuccess?: () => void;
      };
      hidePinTimeout?: {
        domId: string;
        hideTimeout: 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15;
        styles: CSSProperties;
        onSuccess?: () => void;
        onFailure?: () => void;
      };
    };
  };
}

export interface MarqetaShowItem {
  domId: string;
  format?: boolean;
  styles?: {
    span?: CSSProperties;
    'span:hover'?: CSSProperties;
  };
  mode?: 'transparent';
  onCopySuccess?: () => void;
  onCopyFailure?: () => void;
}