UX Toolkit Getting Started

The UX Toolkit environment comprises several elements:

The Toolkit’s JavaScript code, which you add to your application environment. This code is used to inject UX Toolkit UI components in your customer application as native web components, with any PCI data in iframes.
Studio, a web-based environment you use to configure and style the theme applied to the UI components so they align with your customer application’s brand.
The Marqeta platform’s APIs, to which you send your card program’s transaction- and account-related API calls. These interactions are presented by the UX Toolkit UI components and displayed for your cardholders in your customer application. You use the Marqeta platform to authenticate with Studio, and the Marqeta platform is where you upload your Studio theme to once it is finalized.
The Marqeta platform’s private sandbox, a secure environment where you develop and test your code before deploying to production.

Important
This version of UX Toolkit supports only prepaid and debit card programs in the United States.

This page walks you through setting up your environment and rendering a UX Toolkit UI component using native web components on your application or webpage.

Installation

You must install UX Toolkit before it can be used in your customer application. To add UX Toolkit to your application, you can reference it by adding a script tag to the <head> element of your HTML. In the example below, prgmshrtcde represents the short code associated with your card program, and 0 represents the major version number of the latest UX Toolkit web components release. To see the latest major.minor.patch version of the web components, access Studio. The version number is given at the top of the page. The script tag’s crossorigin property allows your site to store the exact version of the script you are using. This value is downloaded in a session cookie, for example uxToolKitVersion: 1.0.0, and is provided to ensure a consistent user experience.

HTML

<script type="module" src="https://web.ux-toolkit.marqeta.com/prgmshrtcde/releases/1/index.js" async crossorigin="require-credentials"></script>

For a more complete example of what your HTML might look like, see Rendering a UI component.

Session integration tutorial

This section shows you how to create a session with a cardholder in Marqeta’s UX Toolkit, as well as how you should interact with the session. Session integration provides Marqeta with a secure way to expose sensitive card data directly to your cardholder, without requiring your servers or application to store, transmit, or process the card data in any way. Marqeta is fully PCI-Service Provider Level 1 compliant and provides the server with which your cardholders’ devices will interact. For a visual representation of how the native web components and iframes are displayed, see About UX Toolkit. Marqeta also hosts the JavaScript files for UX Toolkit, as well as the optional theme objects you upload to the Marqeta platform so they can be applied to the UI components used by your customer application. Theme objects are used to customize the UI components to match the style of your customer application. For more information on creating a Studio theme, see Designing a theme with Studio. UX Toolkit’s default language is American English. However, the UX Toolkit internationalization feature allows you to display UI components in any of Marqeta’s supported languages. For this, you can use Marqeta’s translation files, or you can upload custom translation files that will allow you to tailor UI components in your desired language. For a full list of keys that you can use in your custom translation files, contact your Marqeta onboarding specialist.

Note
If you want to upload custom translation files, you must do this during the authentication process.For detailed information about uploading your custom translation files, see the Upload custom translation files section on the UX Toolkit SDK page.

Note
This tutorial assumes you have already worked with Marqeta to enable UX Toolkit for your program. You cannot complete these steps in the public sandbox environment.

Requirements

In order to begin implementation, your platform must be able to uniquely identify your cardholders on the platform by means of a user token. This unique user identifier is generated as part of creating a user via the POST /users endpoint. For more information, see Users.

Authentication workflow

UX Toolkit uses a secure, Demonstrating Proof of Possession (DPoP)-based authentication methodology using OAuth 2.0. OAuth 2.0 is the industry-standard authorization framework that lets your application securely access data without ever handling users’ credentials directly. Instead of sending a username and password on every request, your server exchanges tokens with an authorization server, minimizing risk and giving you fine-grained control over who can do what, and for how long. DPoP is a security mechanism within OAuth 2.0 that enhances token security by requiring the client to prove it possesses the private key used to obtain the token. This mechanism prevents unauthorized use of leaked or stolen tokens by binding the token to the client’s private key. Below is an overview of the UX Toolkit authentication workflow.

The customer’s web application renders their page and initializes bootstrapping, passing the URL to the Customer’s Authentication API as a parameter.

The UX Toolkit SDK generates a public/private key pair. The private key pair is used to sign the DPoP proof header, while the public key will be used later by the Identity Provider (IdP) or UX Toolkit API for validation.

The DPoP header is passed to the Customer’s Authentication API, and then passed through to the OAuth server (UX Toolkit API). The DPoP header is a short-lived JSON Web Token (JWT) that includes the public key and is signed by the private key. Along with the DPoP header, the Customer’s Authentication API will generate and pass an additional client assertion token in order to successfully request the access token.

The OAuth server issues a DPoP-bound OAuth token, which adds the thumbprint of the public key as one of the properties of the OAuth JWT token. Note that a new, unique DPoP proof token is generated for every request made to the UX Toolkit API. If the OAuth token is ever compromised, it cannot be used without the DPoP private key.

The UX Toolkit API validates the DPoP header it receives for each API request. Then, it matches the public key in the header with the thumbprint in the OAuth token to confirm that the sender has possession of the private key and is the owner of the OAuth token.

Note
UX Toolkit components automatically request a new access token from the Customer Authentication API when the access token nears expiration (within 60 seconds of expiration) or has already expired.

In order to authenticate UX Toolkit via OAuth, you need to complete the following steps:

Generate your RSA key pair

Set up your API URL

Pass your endpoint via the bootstrap function

Create your client assertion token

Request your OAuth access token

Return your OAuth access token

Generate your RSA key pair

To authenticate UX Toolkit via OAuth, you must first generate a unique 2048-bit RSA key pair for each of your Marqeta programs. Marqeta recommends using OpenSSL to generate these RSA key pairs.

Important
Do not reuse the same key pairs for two different Marqeta Programs. Likewise, do not reuse the same key pairs for production and sandbox environments.

When your Marqeta representative creates your program, you must provide them with the public key as an X.509 certificate encoded in Privacy Enhanced Mail (PEM) format. Step 1 Generate a private key in PEM format using the following command:

Important
Never share the private key that you generate in this step, not even with Marqeta.

Pem

openssl genrsa -out myprogram_private_key.pem 2048

Step 2 Extract the public key in PEM format using the following command, which allows you to safely share the public key via email without revealing the details of the private key.

Pem

openssl rsa -in myprogram_private_key.pem -outform PEM -pubout -out myprogram_public_key.pem.pub

The following code shows an example of the contents of a myprogram_public_key.pem.pub PEM file as an X.509 certificate.

Pem

----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx +wIDAQAB -----END PUBLIC KEY-----

Step 3 Send the public key to your Marqeta representative as an X.509 certificate in PEM format, as shown in the previous code example.

Important
While it is safe to send the public key to your Marqeta representative, Marqeta strongly advises that you safeguard the private key. Never share the private key with anyone outside your organization.

Set up your API URL

When configuring your apiEndpoint, you must ensure that your API server allows cross-origin requests from Marqeta’s UX Toolkit web domain. To allow cross-origin requests, you must include the property Access-Control-Allow-Origin in the HTTP response header, as shown in the code example that follows.

Note
You should only add this property to the HTTP response header if you plan on using Marqeta’s iFrame content as mobile webviews.

JavaScript

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', 'https://web.ux-toolkit.marqeta.com');
  next();
});

Including the HTTP response header ensures that requests originating from the Marqeta web client will not be blocked by Cross-Origin Resource Sharing (CORS) policies. Without this header, requests from https://web.ux-toolkit.marqeta.com will fail due to CORS restrictions, and Marqeta will not be able to successfully interact with your OAuth endpoint. You can download an example OpenAPI definition for reference.

Pass your endpoint via the bootstrap function

After the Customer Authentication API endpoint is live, you must then pass the endpoint to the bootstrap() function. To bootstrap UX Toolkit, call the bootstrap() function to initiate the session referenced by your apiEndpoint. Include any API headers at this point, load your theme for consumption by the UI components, and, optionally, upload any custom translation files that you need for your application. You can call the bootstrap() function as shown below.

Note
The apiHeadersResolver property can accept a HeadersInit object as shown in the following code example, or a method (synchronous or asynchronous) that returns a HeadersInit object.In this code sample, there are three optional fields: envName, themeName, and languageCode. Include these fields if you want to specify the environment in which you are working (sandbox or production), use a custom theme, or use custom translation files.

The following table describes fields used when calling the bootstrap() function.

Field	Description
`authParams`	This object contains the following elements: - `apiEndpoint` (Required): The string value of a fully-qualified URL representing your authentication API endpoint. For more information about authentication, see Authentication workflow. - `apiHeadersResolver` (Optional): This object is used to pass any session or auth token headers to your authentication API endpoint for the purpose of authenticating users with your application.
`envName`	(Optional) Indicates which environment is being targeted. Allowable values for this field are `sandbox` or `production`. The default value of this field is `production`.
`themeName`	(Optional) The name of an existing theme that was created using the `/theme` endpoint. The default value of this field is `default`. For more information on the `/theme` endpoint, see Upload theme object.
`languageCode`	(Optional) The language code representing the target language of the custom translation files you uploaded using the `/translations` endpoint. The default language of UX Toolkit web components is American English (`en-US`). For more information about the `/translations` endpoint, see Upload custom translation files.

JavaScript

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://test-customer-endpoint/oauth/token",
    apiHeadersResolver: { `//` OPTIONAL
      "Authentication": "Bearer your-website-session-token-here"
    },
  },
  envName: "sandbox",
  themeName: "new-theme-name",
  languageCode: "es-ES"
})

Create your client assertion token

The client assertion token must be signed with the private key that you generated in the Generate your RSA key pair section. Marqeta recommends that you construct the token using standard tooling or third-party libraries that support this functionality out of the box, rather than implementing them from scratch yourself. To learn more about supporting libraries, visit JWT.io. The Node.js script below uses a jose package to generate the assertion:

JavaScript

const { SignJWT } = require('jose')
const crypto = require("crypto");
const uuid = require("uuid");

async function main() {
 const privateKeyPEM = crypto.createPrivateKey(/**
   Read the content of your private key here. We recommend to store your private key
   in a secure infrastructure.
 */);

 const jwt = await new SignJWT({})
   .setProtectedHeader({
      alg: 'RS256', // or RS384 or PS256
   })
   .setIssuedAt()
   .setIssuer('CLIENT_ID_HERE')
   .setSubject('CLIENT_ID_HERE')
   .setAudience('https://ux-toolkit-api.marqeta.com/')
   .setExpirationTime('1m')
   .setJti(uuid.v4())
   .sign(privateKeyPEM);
  console.log(jwt)
}

main();

Request your OAuth access token

Send a POST request to the /oauth/token endpoint with your client credentials and include the DPoP proof JWT in a DPoP header. Use this endpoint to generate your UX Toolkit OAuth access token. The token you generate enables access to the specified account and is returned to the UX Toolkit client. For more information about working with the POST /oauth/token endpoint to create a UX Toolkit OAuth access token, see Generate UX Toolkit OAuth access token. If you prefer to make the API call by executing a cURL command, use the sample cURL below:

cURL

curl --location --request POST 'https://ux-toolkit-api.marqeta.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header "DPoP: $DPOP_PROOF" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode "client_assertion=$CLIENT_ASSERTION" \
  --data-urlencode 'user_token=some-fancy-user-token' \
  --data-urlencode 'audience=https://ux-toolkit-api.marqeta.com/'

Return your OAuth access token

After the Customer Authentication API has successfully generated the client assertion and exchanged it with the OAuth endpoint for an access token, you must send the resulting access token back to the UX Toolkit client.

Rendering a UI component

Once you have bootstrapped UX Toolkit, rendering UI components in your application is straightforward. Place the HTML tags for the components into the body of your application code, as shown below. In this example, prgmshrtcde in the script tag represents the short code associated with your card program, and 1 represents the major version number of the latest UX Toolkit web components release. To see the latest major.minor.patch version of the web components, access Studio. The version number is given at the top of the page.

HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Your Customer Application</title>
    <script type="module" src="https://web.ux-toolkit.marqeta.com/prgmshrtcde/releases/1/index.js" async crossorigin="require-credentials"></script>
    <script>
      window.addEventListener("load", (event) => {
        window.marqeta.bootstrap({
          authParams: {
            apiEndpoint: "https://test-customer-endpoint/oauth/token",
            apiHeadersResolver: { `//` OPTIONAL
              "Authentication": "Bearer your-website-session-token-here"
            },
          },
          envName: "sandbox",
          themeName: "new-theme-name",
          languageCode: "es-ES"
        });
      });
    </script>
  </head>
  <body>
    <h1>Your Customer Application</h1>
    <div>
      <!-- Drop the UX Toolkit UI components here and -->
      <!-- they will render with the correct details -->
      <mq-account></mq-account>
      <!-- Some components provide attributes to control their behavior -->
      <mq-activate-card
        card-token="{CARD_TOKEN_HERE}"
        show-title="true"
        show-description="true"
      ></mq-activate-card>
    </div>
  </body>
</html>

Your customer application will display the requested UI component, automatically injecting any PCI data into a secure iframe.

Listening to events

A custom UI component event is typically emitted whenever a noteworthy action or behavior occurs within that UI component. You can develop your application to listen and respond to whatever events matter to your use cases.

Linking behavior between UI components

You can link the behavior between two UI components by adding event listeners for specific events. In the example below, an event listener is listening for an mqCardListActionHook event before setting the selected card’s unique token to the value stored in cardToken:

JavaScript

document.querySelector('mq-card-list')
  .addEventListener('mqCardListActionHook', (e) => {
    const { type, data: { cardToken } } = e.detail;
    if (type === 'CARD_SELECTED') {
      document.querySelector('mq-card')
        .setAttribute('card-token', cardToken);
    }
  });

In the following example, an event listener is listening for an mqTransactionListHook event. If the requested operation is to view a transaction, a <div> element is created to contain the transaction. Your application can then display the transaction details in a modal window, including the Report a problem button for disputable transactions.

JavaScript

document.querySelector('mq-transaction-list')
  .addEventListener('mqTransactionListHook', (e) => {
    const { type, data: { transactionToken } } = e.detail;
    if (type === 'VIEW_TRANSACTION') {
      const modalContainer = document.createElement('div');
      modalContainer.innerHTML = `
        <mq-transaction show-report-problem-cta="DISPUTABLE" transaction-token="${transaction-token}"></mq-transaction>
      `;
      Popper.createPopper(document.body, modalContainer, {
        placement: 'center',
      });
    }
  });

For more information on the specific events you can listen for, see the Events section of each of the UI components described in Working with UX Toolkit Web Components.

Working with themes

UX Toolkit UI components come with a default theme; however, you can choose to customize this theme so it aligns more closely with your brand. For more information, see Designing a theme with Studio. After you have developed your theme using the Studio interactive design environment, save it as a JSON file then upload a copy of it to the Marqeta platform, as described in Uploading a Studio theme. The example cURL below uploads a theme named new-theme-name to the Marqeta platform:

cURL

curl --location 'https://ux-toolkit-api.marqeta.com/api/v1/theme' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{BASE64_APPLICATION_AND_ADMIN_ACCESS_TOKENS}}' \
--data '{
    "theme_name": "new-theme-name",
    "theme": {{THEME_JSON_HERE}}
}'

Update the call you make to Marqeta’s bootstrap() method to include the theme:

JavaScript

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://test-customer-endpoint/oauth/token",
    apiHeadersResolver: { `//` OPTIONAL
      "Authentication": "Bearer your-website-session-token-here"
    },
  },
  envName: "sandbox",
  themeName: "new-theme-name",
  languageCode: "es-ES"
})

Choosing card art

UX Toolkit’s web components allow you to upload suitable card art to enhance the cardholder experience offered by your application. You can submit up to three images for each of the card products in your program:

An image displayed on the front of the card
An image displayed on the back of the card (digital cards only, not for virtual cards)
A thumbnail-sized image of the image displayed on the front of the card

If you do not upload card art for your program, default images are displayed by UX Toolkit. The card art you choose is displayed in the Studio interactive design environment and in your application as part of the Card component and the List Cards component, with the capability to expand to other UI components in the future. It is not used elsewhere by the Marqeta platform, for example to place a bulk order for physical cards. The card art images provided below are meant to serve as a base to build your card art template.

Important
The card art you select for your program must be preapproved by Marqeta, your bank, and the card network. It should adhere to the guidelines set forth by the card network and may include details that are part of the bank approval process, such as the issuing bank name. Contact your Marqeta representative if you would like to know more about the card network guidelines related to card art.

Digital (physical) cards

Front of card

This card art template is a digital version of the front of the physical card.

UX Toolkit digital card template front view

Back of card

This card art template is a digital version of the back of the physical card.

UX Toolkit digital card template back view

Thumbnail of card

The thumbnail is an optional scaled-down version of the card art representing the front of the physical card. If you do not submit a thumbnail for your theme, default imagery from the card network will be displayed instead.

Virtual cards

Front of card

This card art template represents the virtual card. Virtual cards have no associated back-of-card image.

Thumbnail of card

The thumbnail is an optional scaled-down version of the card art representing the virtual card. If you do not submit a thumbnail for your theme, default imagery from the card network will be displayed instead.

Card art specifications

The images you submit must adhere to the following specifications:

Name	Description
File format	Portable network graphics file (`*.PNG`)
Image orientation	Landscape only
File size on disk	Maximum of 5 MB per image NOTE: Although the file you choose could be up to 5 MB in size, it will probably be much smaller than the permitted maximum. Avoid using a large file that must be resized for display by the UI components.
Image size on screen	- Front/back images: 1536 pixels x 969 pixels (proportional to an ISO ID-1 card size) - Thumbnail image: 60 pixels x 36 pixels
Corner radius	0.1233” or 3.13182 millimeters
Resolution	72 pixels per inch (PPI)
Color model	RGB
Color depth	16+ bit depth, non-interlaced

Uploading to the Marqeta platform

After you have selected your images and had them approved by Marqeta, your bank, and the card network, you are ready to upload them to the Marqeta platform for use in Studio. You can upload card art to the Marqeta platform using cURLs or by sending an API request to the /cardproducts/cardart endpoint of the UX Toolkit service. The example cURL below uploads an image file named file.png to the Marqeta platform:

cURL

curl -X POST "https://ux-toolkit-api.marqeta.com/api/v1/cardproducts/cardart" \
-H "Authorization: Basic $(echo -n '{{APPLICATION_TOKEN}}:{{ACCESS_TOKEN}}' | base64)" \
-F "program_short_code={{program_short_code}}" \
-F "card_product_token={{card_product_token}}" \
-F "asset_type={{asset_type}}" \ ### front | back | thumbnail
-F "file=@W/path/to/your/file.png"

You can also upload card art to the Marqeta platform by sending a POST request to the /cardproducts/cardart endpoint as a multi-part form data request, as described in Upload card art.

Using custom translation files

UX Toolkit web components are automatically set to American English as the default. However, Marqeta enables you to change the language of web components as part of the UX Toolkit internationalization feature. You can change the language of web components by uploading custom translation files using the /translations endpoint and then including them in the bootstrap() function. For more information about the /translations endpoint, see the Upload custom translation files section on the UX Toolkit SDK page.

Important
Before uploading your translation files using the /translations endpoint, ensure that they are linguistically accurate and representative of the user experience.

Working with custom translation files

Note
If you are using a custom theme, you must upload it as described in Uploading a Studio theme prior to calling the bootstrap() function.

To include custom translation files when you bootstrap UX Toolkit, perform the following steps:

Ensure that your custom translation files are linguistically accurate and representative of the user experience.
Upload your custom translation files using the translations endpoint as described in the Upload custom translation files section on the UX Toolkit SDK page.
Test your files in Studio.
Update the call you make to Marqeta’s bootstrap() function to include the language code, as shown in the code example below.
Execute the bootstrap() function.

JavaScript

window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://test-customer-endpoint/oauth/token",
    apiHeadersResolver: { `//` OPTIONAL
      "Authentication": "Bearer your-website-session-token-here"
    },
  },
  envName: "sandbox",
  themeName: "new-theme-name",
  languageCode: "es-ES"
});

Testing in UX Toolkit Studio

You can use Marqeta’s Studio interactive design environment to test translation values.

Note
To perform a test of the custom translation files, you must be authenticated within Studio.

Request the translations object file for your target language from Marqeta.
Customize the values in the object file in your target language.
Send a request using the object with customized values to the /translations endpoint, as described in the Upload custom translation files section on the UX Toolkit SDK page. This should return a successful response message.

Important
If you are missing required parameters in the translations object file (programShortCode, languageCode, and translations), it will return a 400 Bad request error.

Authenticate in Studio using your access token.
In Studio, click on the globe icon in the top menu navigation bar to confirm that changes to your custom translation files have been applied. Available languages are listed in the drop-down menu beneath the globe icon.
Select a language from the list.

Note
The languages that Marqeta supports are listed under the globe icon. Use the Customize tab to view any updates that you have made to the web components’ display language.

Guides

​Installation

​Session integration tutorial

​Requirements

​Authentication workflow

​Generate your RSA key pair

​Set up your API URL

​Pass your endpoint via the bootstrap function

​Create your client assertion token

​Request your OAuth access token

​Return your OAuth access token

​Rendering a UI component

​Listening to events

​Linking behavior between UI components

​Working with themes

​Choosing card art

​Digital (physical) cards

​Front of card

​Back of card

​Thumbnail of card

​Virtual cards

​Front of card

​Thumbnail of card

​Card art specifications

​Uploading to the Marqeta platform

​Using custom translation files

​Working with custom translation files

​Testing in UX Toolkit Studio

Installation

Session integration tutorial

Requirements

Authentication workflow

Generate your RSA key pair

Set up your API URL

Pass your endpoint via the bootstrap function

Create your client assertion token

Request your OAuth access token

Return your OAuth access token

Rendering a UI component

Listening to events

Linking behavior between UI components

Working with themes

Choosing card art

Digital (physical) cards

Front of card

Back of card

Thumbnail of card

Virtual cards

Front of card

Thumbnail of card

Card art specifications

Uploading to the Marqeta platform

Using custom translation files

Working with custom translation files

Testing in UX Toolkit Studio