Using Marqeta.js

Companies that store, transmit, or process sensitive card data, including the primary account number (PAN), card verification value (CVV2), expiration date, and personal identification number (PIN) must comply with the Payment Card Industry Data Security Standard (PCI DSS). Achieving PCI DSS certification is both time consuming and expensive.

Marqeta.js offloads some of the PCI compliance burden (for certain use cases) by enabling the encrypted transmission of sensitive card data. Marqeta is fully PCI-Service Provider Level 1 compliant and handles the unencrypted sensitive card data for you. Your servers never store, transmit, or process the card data.

The iframes injected by Marqeta.js enable you to control the styling and layout of the HTML pages you serve to client applications, while delegating secure handling of sensitive data to Marqeta servers. They also provide the transparent button UI elements used for copying sensitive data to the clipboard. These elements are transparent so you can overlay them over your custom user interface to intercept click events. They require no customization. You create and style pages in whatever manner you desire, and Marqeta.js inserts the card data and button UI elements into the page locations specified in the HTML.

The following process describes how Marqeta.js injects the iframes into your application. See the tutorials on this page for more details.

The .bootstrap() method of Marqeta.js requires a configuration object, which defines the attributes and behaviors of the iframes. Nested under the configuration object is the component object, which accepts either a showPan or a pinReveal object, depending on the action you want to complete. In both cases, you must include the ID of the "div" element into which Marqeta.js injects the individual iframes of card data.

More information on the objects is given the section below.

The configuration object

You can add transparent iframes to your application or webpage that capture clicks to copy a card’s PAN, CVV2, or expiration date to the clipboard of the cardholder’s device. For example, in a POS financing scenario, your cardholders can click the buttons provided by the .copyToClipboard() method to help them avoid manually copying card data from a newly issued virtual card to the vendor’s application where they are making a purchase.

Each iframe is associated with a parent div element. Your application or webpage requires a separate parent div element for each card data element you want to copy to the clipboard.

The iframe containing the transparent Copy to Clipboard button is positioned precisely to the bounds of the parent div, so that it can intercept all click events. If your button is not responding to clicks, ensure that the iframe is positioned correctly. By handling the clicks within an iframe, your application avoids entering PCI scope.

You must supply your own visible button UI element inside each parent div that contains the card data to copy.

To respond to clicks within the parent div, you must specify a callback function for the onCopySuccess field. This event handler is triggered when data is successfully copied to the clipboard in response to a click event, enabling you to perform an action such as updating your application’s user interface or webpage.

The following HTML example displays a Copy PAN to Clipboard button as an icon:

When the cardholder clicks any of the transparent iframes, Marqeta.js displays a toast notification in the lower-left corner of the application window or webpage. The toast notification informs the cardholder of the implications of copying sensitive card data to the clipboard. After Marqeta.js displays the notification, it is not presented to the cardholder again on the same device for 90 days to optimize the user experience. Your site must allow access to localStorage because that is where Marqeta.js keeps track of the last time the notification was presented.

The toast notification has default inline styles that you can override to match your application or webpage’s design by using the !important rule.

Marqeta.js also provides a .destroy() method. Run marqeta.destroy() to reset Marqeta.js and any existing configurations, by clearing all the listeners.

In some situations, you might prefer to call marqeta.bootstrap() instead of calling marqeta.destroy(). One example would be if you wanted to display the data from another card. If you use this approach, however, your client access token will expire. Don’t forget to obtain a new client access token first, as explained in Step 6 of the card data tutorial.

Before integrating with Marqeta.js to display card data, prepare an otherwise blank HTML page.

Create a new HTML file and add the following code:

If you are working in your private sandbox environment, add the following script tag to your HTML:

If you are working in a production environment, add the following script tag to your HTML:

To inject the iframes into your HTML, call the marqeta.bootstrap() method of Marqeta.js from your HTML.

Add the following script tag to your HTML after the reference to Marqeta.js. You’ll need to pass an object to the method, but leave it empty for now.

To present all three pieces of card data, create three div elements—one each for the PAN, expiration date, and CVV2. Assign a unique ID to each div; you will use these IDs in the marqeta.bootstrap() configuration object.

Add the following code to your HTML:

You can use CSS to define the width of the iframes created by Marqeta.js if you need to resize them. You have the option of setting the iframe’s width to a fixed value such as 300 px or to a relative value such as 75%.

If you set the iframe’s width to 100%, it will expand to fill the size of the parent container. In terms of the span, its text will stop wrapping once it is wide enough. In many cases, it is recommended to set the iframe width to 100%, and then style the parent container to the width you actually need.

Use the configuration object to define how the iframes appear on your webpage. Make sure to include the required data. You can configure Marqeta.js to display any combination of the card’s PAN, CVV2, and expiration date.

In this scenario, you will display the PAN, CVV2, and expiration date, providing the necessary card data for your customer.

You have the option of supplying style-related information inline (see mq-card-pan below) or as a custom style object you create (see the mq-card-exp style object styles.cardExp.styles below).

Add the following object as an argument for the bootstrap() method. Later steps in this tutorial will explain how to retrieve the data that replaces the placeholder text.

Each time you want to display a virtual card’s sensitive data, you must request a new client access token. The client access token expires after five minutes.

Request a client access token from the Marqeta platform by sending a POST request to the /users/auth/clientaccesstoken endpoint.

Use the following cURL to request an access token. Replace the following placeholder text:

The following is a sample response to a request for a client access token:

After obtaining the client access token, embed it into your JavaScript code in place of the CLIENT ACCESS TOKEN placeholder text. For this tutorial, you can manually insert the token into your HTML code. In a production situation, however, you should programmatically insert the token before calling the bootstrap() method.

Use the following set of HTML buttons to enable cardholders to copy card data elements to the clipboard of their device.

Add the following HTML to the page, at the top of the <body> tag, after the line <div id='mq-card-cvv'></div>:

Now modify the marqeta.bootstrap() method to configure these iframes:

A hover state is a style configuration that you pass to the marqeta.bootstrap() method. The parent div receives hover events from its associated iframe.

To implement a hover state, add the following CSS statements to the HTML page inside the <head> tags:

When the page loads, marqeta.bootstrap() injects the iframe populated with card data and styles into the inner container div elements mq-card-pan, mq-card-exp, and mq-card-cvv, as specified in the configuration object. The Copy to Clipboard iframes are also injected if you choose to integrate the Copy to Clipboard functionality.

Before integrating with Marqeta.js to display card data, prepare an otherwise blank HTML page.

Create a new HTML file and add the following code:

If you are working in your private sandbox environment, add the following script tag to your HTML:

If you are working in a production environment, add the following script tag to your HTML:

To inject the iframes into your HTML, call the marqeta.bootstrap() method of Marqeta.js from your HTML.

Add the following script tag to your HTML after the reference to Marqeta.js. You’ll need to pass an object to the method, but leave it empty for now.

To present the cardholder’s PIN, create a div element for it here. Assign a unique ID to the each div; you will use this ID in the component object of marqeta.bootstrap().

Add the following code to your HTML:

You can use CSS to define the width of the iframes created by Marqeta.js if you need to resize them. You have the option of setting the iframe’s width to a fixed value such as 300 px or to a relative value such as 75%.

If you set the iframe’s width to 100%, it will expand to fill the size of the parent container. In terms of the span, its text will stop wrapping once it is wide enough. In many cases, it is recommended to set the iframe width to 100%, and then style the parent container to the width you actually need.

Use the component object to define how the iframes appear on your webpage. Make sure to include the required data. In this scenario, you will display the cardholder’s PIN.

You have the option of supplying style-related information inline (see mq-card-pin below) or as a custom style object you create (see the mq-card-exp style object styles.cardExp.styles in the Card Data tutorial above).

Add the following object as an argument for the bootstrap() method. Later steps in this tutorial will explain how to retrieve the data that replaces the placeholder text.

The timeout value is the number of seconds after which Marqeta.js will hide the PIN from view as a safety precaution. In this step, you also add the styling information that will apply to the PIN timer’s message.

If your cardholder clicks the toggle PIN button while the timer is running, the timer will end and Marqeta.js will hide the PIN from view. If the toggle PIN button is clicked again, the timer will start counting down from the beginning (and not resume the timer’s previous countdown position).

Add the following code to your HTML:

Each time you want to display a virtual card’s sensitive data, you must request a new client access token. The client access token expires after five minutes.

Request a client access token from the Marqeta platform by sending a POST request to the /users/auth/clientaccesstoken endpoint.

Use the following cURL to request an access token. Replace the following placeholder text:

The following is a sample response to a request for a client access token:

After obtaining the client access token, embed it into your JavaScript code in place of the CLIENT ACCESS TOKEN placeholder text. For this tutorial, you can manually insert the token into your HTML code. In a production situation, however, you should programmatically insert the token before calling the bootstrap() method.

A hover state is a style configuration that you pass to the marqeta.bootstrap() method. The parent div receives hover events from its associated iframe.

To implement a hover state, add the following CSS statements to the HTML page inside the <head> tags:

When the page loads, marqeta.bootstrap() injects the iframes populated with card data and styles into the inner container div elements of mq-card-pin and mq-toggle-card-pin. The bootstrap() method also injects a div element with the timeout message and styles into the inner container span element mq-pin-timeout.