UX Toolkit Getting Started

Step-by-step instructions for getting access to UX Toolkit and shipping a working integration in your application. The UX Toolkit environment comprises several elements:

The Toolkit’s JavaScript code, which you add to your application environment. This code injects UX Toolkit UI components into 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. You also use the Marqeta platform to upload your Studio theme.
The Marqeta platform’s private sandbox, a secure environment specifically created for your program, where you develop and test your code before deploying to production. The private sandbox should not be confused with the public sandbox, which is a sample sandbox automatically provisioned for any user who logs in to marqeta.com.

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

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

Get access

Enable UX Toolkit for your program

UX Toolkit is enabled per-program by your Marqeta representative. To begin, contact your Marqeta onboarding specialist or account representative to request UX Toolkit access for your program. They will provide your program short code (referenced as prgmshrtcde throughout these docs) and walk you through onboarding requirements. You will also need to uniquely identify your cardholders on the platform via 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 in the Marqeta core API reference.

Create RSA keys

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

Important
Do not reuse the same key pair across two different Marqeta programs. Likewise, do not reuse the same key pair 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. This 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 contents of myprogram_public_key.pem.pub will look like this X.509 certificate:

Pem

Step 3 Send the public key to your Marqeta representative as an X.509 certificate in PEM format.

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.

I have access — how do I get started?

Prerequisite
Customer Authentication API. Before you can render any UX Toolkit components, you must build a Customer Authentication API on your backend that handles the OAuth 2.0 + DPoP token exchange with Marqeta. This is the single most-missed step during onboarding. See Customer Authentication API for the full implementation guide.

Quick start

The following minimal HTML example renders a single UX Toolkit component (mq-card) on a page. It demonstrates the three things you need to display a working component: the script tag, the bootstrap() call, and the component element itself. In this example, prgmshrtcde 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, access Studio; the version number is shown at the top of the page.

HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <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", () => {
        window.marqeta.bootstrap({
          authParams: {
            apiEndpoint: "https://your-domain.com/oauth/token",
            apiHeadersResolver: { // OPTIONAL
              "Authentication": "Bearer your-website-session-token-here"
            },
          },
          envName: "sandbox",
        });
      });
    </script>
  </head>
  <body>
    <h1>Your Customer Application</h1>
    <mq-card card-token="{CARD_TOKEN_HERE}"></mq-card>
  </body>
</html>

The crossorigin property on the script tag allows your site to store the exact version of the script you are using. This value is downloaded in a session cookie (e.g., uxToolKitVersion: 1.0.0) to ensure a consistent user experience. Your customer application will display the requested UI component, automatically injecting any PCI data into a secure iframe.

What’s next?

Once your Quick Start is rendering, here’s where to go next:

Customize the look-and-feel. Pass additional options to bootstrap() (theme, language, environment) and design a custom theme. See Customizing UX Toolkit.
Add more components. Browse the catalog in About UX Toolkit and the canonical reference in Studio.
Integrate component events. Listen for events to wire up linked behavior between components. See Integrating Components.
Embed in a mobile webview. If your application is a native mobile app, see Working within Native Webviews.

​Get access

​Enable UX Toolkit for your program

​Create RSA keys

​I have access — how do I get started?

​Quick start

​What’s next?

Get access

Enable UX Toolkit for your program

Create RSA keys

I have access — how do I get started?

Quick start

What’s next?