UX Toolkit Getting Started

Step-by-step instructions for getting access to UX Toolkit and shipping a working integration in your application.

Note
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.

The UX Toolkit environment comprises several elements:

The UX Toolkit 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 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 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 signs in to marqeta.com.

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

Get access

Note
You will be required to complete these steps for your production environment once you are ready to move from sandbox to production.

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. In return, they provide the OAuth client ID and the key ID (kid) for that program and environment. Your Customer Authentication API uses the client ID to identify itself when requesting access tokens, and sends the key ID in the header of its client assertion.

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.

Note
Your Customer Authentication API requests access tokens from the dedicated OAuth host at https://secure-sandbox.marqeta.com in sandbox, or https://secure.marqeta.com in production. If you are on version 1 of UX Toolkit, your integration requests tokens from the UX Toolkit API instead. It continues to work, and you can move it at your own pace. To learn how, see How to migrate UX Toolkit to dedicated OAuth.

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 2 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.

Note
When setting up the Quick start for your production environment, you must replace envName: “sandbox” with envName: “production”

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/2/index.js" async crossorigin="anonymous"></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 attribute on the script tag controls whether the browser sends credentials when it requests the script. Set it to anonymous. The HTML specification recognizes only anonymous and use-credentials, and browsers fall back to anonymous for any other value. Do not set it to use-credentials: the content delivery network (CDN) serves the script with Access-Control-Allow-Origin: *, and browsers block credentialed requests against a wildcard origin. To ensure a consistent user experience, the CDN records the exact version of the script it serves in a session cookie (for example, uxToolkitVersion: 1.21.1). The CDN sets this cookie regardless of the crossorigin value, and the cookie is HttpOnly, so your own JavaScript cannot read it. 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?