Marqeta.com
Support
/
10 minute read
December 16, 2020

Using Marqeta.js

Marqeta provides a JavaScript library that enables you to display sensitive card data in your application or webpage while limiting your data security compliance burden.

Marqeta.js injects a set of configurable iframes into your HTML showing the cardholder’s card data. The iframes enable you to display a virtual card without handling sensitive card data on your servers. Instead, Marqeta hosts the data on secure, compliant servers. You can present a complete card—including the PAN, expiration date, and CVV2 elements—or individual elements.

Note
While the Marqeta.js iframe feature reduces your burden of achieving data security compliance, it does not eliminate it entirely, and is only appropriate for certain use cases. Contact your Marqeta representative about using the Marqeta.js library.

At the end of the guide, you should understand:

  • How to integrate with Marqeta.js.

  • How to obtain a client access key.

  • How to inject the Marqeta.js iframes into your HTML.

Prerequisites

Concepts

Data security compliance

Companies that store, transmit, or process sensitive card data, including the primary account number (PAN), expiration date, and card verification value (CVV2), 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-Level 1 compliant and handle the unencrypted sensitive card data for you. Your servers never store, transmit, or process the card data.

Dynamic card data iframes

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 the sensitive data to Marqeta servers. You create and style pages in whatever manner you desire and Marqeta.js inserts the card data into the page locations specified in the HTML.

Note
To display virtual cards within a mobile application, you can embed the iframes using a web element.
Encryption and card data flow

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

How Marqeta.js injects iframes into your application

Is this helpful?

Yes
No
  • Your application’s back end requests a client access token.

  • The Marqeta API creates a base64-encoded client access token. This token enables access to the specified card and will expire after five minutes.

  • Your back end passes the client access token to your JavaScript.

  • Your JavaScript injects the client access token into the

    marqeta.bootstrap()
    method.

  • Your JavaScript executes

    marqeta.bootstrap()
    , which initializes and configures Marqeta.js.

  • Marqeta.js injects the card data into the HTML container using separate iframes for the card’s PAN, CVV2, and expiration date.

  • The HTML page displays the card data.

The configuration object

The

.bootstrap()
method of Marqeta.js requires a configuration object, which defines the attributes and behaviors of the iframes. You must include the ID of the div element into which Marqeta.js injects the individual iframes of card data.

The configuration object

Fields Description

clientAccessToken

string
Required

Client access token obtained from the Marqeta API.

Allowable Values:

Client access token

integrationType

string
Required

Set to "custom".

Allowable Values:

"custom"

containerId

string
Required

Identifies the outer div element whose child div elements will be injected with PAN, CVV2 and expiration date iframes.

Allowable Values:

Must match the

id
of the outermost "div" element.

showPan

object
Required

Specifies the card data to display and applies typographical styling to the data.

Include the

cardPan
object to display the PAN, the
cardExp
object to display the expiration date, and the
cardCvv
object to display the CVV2 number.

Allowable Values:

Any combination of

cardPan
,
cardExp
, and
cardCvv
objects.

callbackEvents

object
Optional

Defines customizable event handlers that are executed upon success or failure of iframe rendering.

Allowable Values:

Existing object.

Within the configuration object, you must include the

showPan
object. The
showPan
object specifies which card attributes to display. It can contain the following objects:

  • cardPan
    — The card’s PAN

  • cardExp
    — The card’s expiration date

  • cardCvv
    — The card’s CVV2

You can include any combination of these objects within the

showPan
object. Objects included within the
showPan
object have their associated values injected as iframes within the div container you specified in the configuration object. For each included object, you must specify the div element that contains the iframe.

You can also configure the appearance of the card data using the

styles
object within each of the
cardPan
,
cardExp
, and
cardCvv
objects.

Object Supported Selectors Supported Attributes

cardPan

span, span:hover

color, font-family, font-size, background, font-weight, letter-spacing

cardExp

span, span:hover

color, font-family, font-size, background, font-weight, letter-spacing

cardCvv

span, span:hover

color, font-family, font-size, background

The showPan.cardPan and showPan.cardExp objects

Fields Description

domId

string
Required

Associates the cardPan and cardExp elements with their corresponding div elements.

Allowable Values:

Must match the DOM ID of the corresponding "div" element.

For example,

showPan.domId
must match the id attribute of the div element that will contain the card PAN iframe.

format

boolean
Optional

Set to

true
to format the element’s content.

The content of
cardPan
is formatted as:
"XXXX XXXX XXXX XXX"

The content of
cardExp
is formatted as:
"XX/XX"

Allowable Values:

true
,
false


Default value:
false

styles

object
Optional

A CSS-like style object applied to the iframe holding the card data.

Allowable Values:

Existing object

styles.\

object
Optional

Replace

\
with one of the supported selector values.

Supported selectors:
span
,
span:hover


Supported CSS attributes:
color
,
font-family
,
font-size
,
background
,
font-weight
,
letter-spacing


Note
CSS importing schemes such as
@import
and
@url
are not supported.

Allowable Values:

Existing object

The showPan.cardCvv object

Fields Description

domId

string
Required

Associates the cardCvv element with its corresponding div element.

Allowable Values:

Must match the DOM ID of the corresponding "div" element.

That is,

cardCvv.domId
must match the id attribute of the div element that will contain the card CVV2 iframe.

styles

object
Optional

A CSS-like style object applied to the iframe holding the card data.

Allowable Values:

Existing object

styles.\

object
Optional

Replace

\
with one of the supported selector values.

Supported selectors:
span
,
span:hover


Supported CSS attributes:
color
,
font-family
,
font-size
,
background


Note
CSS importing schemes such as
@import
and
@url
are not supported.

Allowable Values:

Existing object

The

callbackEvents
object specifies the methods executed upon success and failure events when rendering the iframes.

The callbackEvents object

Fields Description

onSuccess

event handler
Optional

Executed upon success of iframe rendering.

You can customize the method within this event handler to perform whatever action you want.

Allowable Values:

A method

onFailure

event handler
Optional

Executed upon failure of iframe rendering.

You can customize the method within this event handler to perform whatever action you want.

Allowable Values:

A method

Resetting Marqeta.js

Marqeta.js also provides a

.destroy()
method. Run
marqeta.destroy()
to reset Marqeta.js and any existing configurations.

Tutorial

This tutorial shows you how to display a virtual card’s sensitive data using iframes on your webpage or application. In this scenario, you will display a virtual card’s PAN, expiration date, and CVV2 on an otherwise blank webpage, enabling you to display a virtual card’s data to your customer.

Note
This tutorial assumes you have already worked with Marqeta to enable Marqeta.js for your program.

When you are finished, your HTML code should look like the following:

Copied

Is this helpful?

Yes
No
Step One: Prepare a blank HTML page

Before integrating with Marqeta.js, prepare an otherwise blank HTML page.

Create a new HTML file and add the following code:

Copied

Is this helpful?

Yes
No
Step Two: Reference Marqeta.js

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

Copied

Is this helpful?

Yes
No

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

Copied

Is this helpful?

Yes
No
Step Three: Add a marqeta.bootstrap() method call

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.

Copied

Is this helpful?

Yes
No
Step Four: Add a target div

To present all three pieces of card data, create four divs—one each for the PAN, expiration date, and CVV2, and another to contain the other three divs. 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:

Copied

Is this helpful?

Yes
No
Step Five: Add the bootstrap configuration object

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.

Add the following object as a parameter for the

bootstrap()
method. Later steps in this exercise will explain how to retrieve the data that replaces the placeholder text.

Copied

Is this helpful?

Yes
No
Step Six: Request a client access token

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:

  • YOUR APPLICATION TOKEN

  • YOUR ADMIN ACCESS TOKEN

  • CARD TOKEN

  • YOUR SUBDOMAIN

Copied

Is this helpful?

Yes
No

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

Copied

Is this helpful?

Yes
No

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

bootstrap()
method.

Note
The client access token is a string encoded as Base64. You can decode it to see client access token details including the associated card token.
Step Seven: Run marqeta.bootstrap()

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.

Note
You can check the console of your browser for the success or failure message, as defined in the
callbackEvents
object.

Feedback on this page?

If you feel we can do anything better, please let our team know.