> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UX Toolkit Getting Started

> Step-by-step instructions on how to install and begin working with UX Toolkit.

The UX Toolkit environment comprises several elements:

* The Toolkit’s [JavaScript code](/developer-guides/uxt-getting-started/#_installation), 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](https://studio.ux-toolkit.marqeta.com), 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](https://www.marqeta.com/core-api/introduction/), 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](/core-api/introduction/#_accessing_the_sandbox_environment), a secure environment where you develop and test your code before deploying to production.

<Warning>
  **Important**\
  This version of UX Toolkit supports prepaid and debit card programs in the United States, Canada, and the EU.
</Warning>

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.

<h2 id="_installation">
  Installation
</h2>

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](https://studio.ux-toolkit.marqeta.com). 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 HTML lines wrap theme={null}
<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](/developer-guides/uxt-getting-started/#_rendering_a_ui_component).

<h2 id="_session_integration_tutorial">
  Session integration tutorial
</h2>

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](/developer-guides/about-ux-toolkit/#_ux_toolkit_platform_overview).

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](/developer-guides/uxt-web-components/#_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>
  **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](/core-api/uxt-sdk/#_upload_custom_translation_files) section on the [UX Toolkit SDK](/core-api/uxt-sdk/) page.
</Note>

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

<h3 id="_requirements">
  Requirements
</h3>

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](/core-api/users/).

<h3 id="_authentication_workflow">
  Authentication workflow
</h3>

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.

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-getting-started/uxt-authentication-workflow.svg?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=6f2d525bbd67ac7fd4ff3cf41d71521e" alt="UX Toolkit authentication workflow" width="1989" height="1881" data-path="images/docs/developer-guides/uxt-getting-started/uxt-authentication-workflow.svg" />
</Frame>

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

  <Step>
    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.
  </Step>

  <Step>
    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.
  </Step>

  <Step>
    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.
  </Step>

  <Step>
    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.
  </Step>
</Steps>

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

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

<Steps>
  <Step>
    [Generate your RSA key pair](/developer-guides/uxt-getting-started/#_generate_your_rsa_key_pair)
  </Step>

  <Step>
    [Set up your API URL](/developer-guides/uxt-getting-started/#_set_up_your_api_url)
  </Step>

  <Step>
    [Pass your endpoint via the bootstrap function](/developer-guides/uxt-getting-started/#_pass_your_endpoint_via_the_bootstrap_function)
  </Step>

  <Step>
    [Create your client assertion token](/developer-guides/uxt-getting-started/#_create_your_client_assertion_token)
  </Step>

  <Step>
    [Request your OAuth access token](/developer-guides/uxt-getting-started/#_request_your_oauth_access_token)
  </Step>

  <Step>
    [Return your OAuth access token](/developer-guides/uxt-getting-started/#_return_your_oauth_access_token)
  </Step>
</Steps>

<h4 id="_generate_your_rsa_key_pair">
  Generate your RSA key pair
</h4>

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.

<Warning>
  **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.
</Warning>

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:

<Warning>
  **Important**\
  Never share the private key that you generate in this step, not even with Marqeta.
</Warning>

```pem Pem lines wrap theme={null}
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 Pem lines wrap theme={null}
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 Pem lines wrap theme={null}
----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.

<Warning>
  **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.
</Warning>

<h4 id="_set_up_your_api_url">
  Set up your API URL
</h4>

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>
  **Note**\
  You should only add this property to the HTTP response header if you plan on using Marqeta’s iFrame content as mobile webviews.
</Note>

```javascript JavaScript lines wrap theme={null}
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](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](/developer-guides/cardholder-auth-api.yaml) for reference.

<h4 id="_pass_your_endpoint_via_the_bootstrap_function">
  Pass your endpoint via the bootstrap function
</h4>

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](/developer-guides/uxt-getting-started/#_working_with_themes) for consumption by the UI components, and, optionally, [upload any custom translation files](/developer-guides/uxt-getting-started/#_working_with_custom_translation_files) that you need for your application.

You can call the `bootstrap()` function as shown below.

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

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

| Field          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authParams`   | This object contains the following elements:<br /><br />- `apiEndpoint` (Required): The string value of a fully-qualified URL representing your authentication API endpoint. For more information about authentication, see <a href="/developer-guides/uxt-getting-started/#_authentication_workflow">Authentication workflow</a>.<br />- `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 <a href="/core-api/uxt-sdk/#post_theme_by_name">Upload theme object</a>.                                                                                                                                                                                                                                                                            |
| `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 <a href="/core-api/uxt-sdk/#_upload_custom_translation_files">Upload custom translation files</a>.                                                                                                                                             |

```javascript JavaScript lines wrap theme={null}
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"
})
```

<h4 id="_create_your_client_assertion_token">
  Create your client assertion token
</h4>

The client assertion token must be signed with the private key that you generated in the [Generate your RSA key pair](/developer-guides/uxt-getting-started/#_working_with_custom_translation_files) 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](http://jwt.io/).

The Node.js script below uses a `jose` package to generate the assertion:

```javascript JavaScript expandable lines wrap theme={null}
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();
```

<h4 id="_request_your_oauth_access_token">
  Request your OAuth access token
</h4>

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](/developer-guides/uxt-getting-started/#_authentication_workflow).

If you prefer to make the API call by executing a cURL command, use the sample cURL below:

```sh cURL lines wrap theme={null}
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/'
```

<h4 id="_return_your_oauth_access_token">
  Return your OAuth access token
</h4>

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.

<h2 id="_rendering_a_ui_component">
  Rendering a UI component
</h2>

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](https://studio.ux-toolkit.marqeta.com). The version number is given at the top of the page.

```html HTML expandable lines wrap theme={null}
<!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.

<h2 id="_listening_to_events">
  Listening to events
</h2>

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.

<h3 id="_linking_behavior_between_ui_components">
  Linking behavior between UI components
</h3>

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 JavaScript lines wrap theme={null}
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 JavaScript lines wrap theme={null}
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](/developer-guides/uxt-web-components/).

<h2 id="_working_with_themes">
  Working with themes
</h2>

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](/developer-guides/uxt-web-components/#_designing_a_theme_with_studio).

After you have developed your theme using the [Studio interactive design environment](https://studio.ux-toolkit.marqeta.com), save it as a JSON file then upload a copy of it to the Marqeta platform, as described in [Uploading a Studio theme](/core-api/uxt-sdk/#post_theme_by_name).

The example cURL below uploads a theme named `new-theme-name` to the Marqeta platform:

```sh cURL lines wrap theme={null}
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 JavaScript lines wrap theme={null}
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"
})
```

<h2 id="_choosing_card_art">
  Choosing card art
</h2>

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](https://studio.ux-toolkit.marqeta.com) and in your application as part of the [Card](/developer-guides/uxt-web-components/#_card_component) component and the [List Cards](/developer-guides/uxt-web-components/#_card_list_component) 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.

<Warning>
  **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.
</Warning>

<h3 id="_digital_physical_cards">
  Digital (physical) cards
</h3>

<h4 id="_front_of_card">
  Front of card
</h4>

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

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-getting-started/uxt-digital-card-front.svg?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=d1f0e10d0b99c2bd44991cc42ac4deb0" alt="UX Toolkit digital card template front view" width="300" height="186" data-path="images/docs/developer-guides/uxt-getting-started/uxt-digital-card-front.svg" />
</Frame>

<h4 id="_back_of_card">
  Back of card
</h4>

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

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-getting-started/uxt-digital-card-back.svg?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=b31dbc3f9f752bd2d3781ecc568d086b" alt="UX Toolkit digital card template back view" width="300" height="186" data-path="images/docs/developer-guides/uxt-getting-started/uxt-digital-card-back.svg" />
</Frame>

<h4 id="_thumbnail_of_card">
  Thumbnail of card
</h4>

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.

<h3 id="_virtual_cards">
  Virtual cards
</h3>

<h4 id="_front_of_card_2">
  Front of card
</h4>

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

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-getting-started/uxt-virtual-card.svg?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=93f13e117581bd9b64ed4840f42695c0" alt="UX Toolkit virtual card template" width="301" height="186" data-path="images/docs/developer-guides/uxt-getting-started/uxt-virtual-card.svg" />
</Frame>

<h4 id="_thumbnail_of_card_2">
  Thumbnail of card
</h4>

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.

<h3 id="_card_art_specifications">
  Card art specifications
</h3>

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<br /><br />**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)<br />- **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                                                                                                                                                                                                                         |

<h3 id="_uploading_to_the_marqeta_platform">
  Uploading to the Marqeta platform
</h3>

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](https://studio.ux-toolkit.marqeta.com).

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:

```sh cURL lines wrap theme={null}
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](/core-api/uxt-sdk/#post_card_art).

<h2 id="_using_custom_translation_files">
  Using custom translation files
</h2>

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](/core-api/uxt-sdk/#_upload_custom_translation_files) section on the [UX Toolkit SDK](/core-api/uxt-sdk/) page.

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

<h3 id="_working_with_custom_translation_files">
  Working with custom translation files
</h3>

<Note>
  **Note**\
  If you are using a custom theme, you must upload it as described in [Uploading a Studio theme](/core-api/uxt-sdk/#post_theme_by_name) prior to calling the `bootstrap()` function.
</Note>

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

1. Ensure that your custom translation files are linguistically accurate and representative of the user experience.
2. Upload your custom translation files using the `translations` endpoint as described in the [Upload custom translation files](/core-api/uxt-sdk/#_upload_custom_translation_files) section on the [UX Toolkit SDK](/core-api/uxt-sdk/) page.
3. [Test your files](/developer-guides/uxt-getting-started/#_testing_in_ux_toolkit_studio) in [Studio](https://studio.ux-toolkit.marqeta.com).
4. Update the call you make to Marqeta's `bootstrap()` function to include the language code, as shown in the code example below.
5. Execute the `bootstrap()` function.

```javascript JavaScript lines wrap theme={null}
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"
});
```

<h3 id="_testing_in_ux_toolkit_studio">
  Testing in UX Toolkit Studio
</h3>

You can use Marqeta's [Studio interactive design environment](https://studio.ux-toolkit.marqeta.com) to test translation values.

<Note>
  **Note**\
  To perform a test of the custom translation files, you must be authenticated within [Studio](https://studio.ux-toolkit.marqeta.com).
</Note>

1. Request the translations object file for your target language from Marqeta.
2. Customize the values in the object file in your target language.
3. Send a request using the object with customized values to the `/translations` endpoint, as described in the [Upload custom translation files](/core-api/uxt-sdk/#_upload_custom_translation_files) section on the [UX Toolkit SDK](/core-api/uxt-sdk/) page. This should return a successful response message.

<Warning>
  **Important**\
  If you are missing required parameters in the translations object file (`programShortCode`, `languageCode`, and `translations`), it will return a `400 Bad request` error.
</Warning>

4. Authenticate in [Studio](https://studio.ux-toolkit.marqeta.com) using your access token.
5. 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.
6. Select a language from the list.

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


## Related topics

- [UX Toolkit](/docs/core-api/uxt-sdk.md)
- [UX Toolkit Overview](/docs/developer-guides/uxt-landing-page.md)
- [About UX Toolkit](/docs/developer-guides/about-ux-toolkit.md)
- [Working with UX Toolkit within Native Webviews](/docs/developer-guides/uxt-within-native-webviews.md)
- [Working with UX Toolkit Web Components](/docs/developer-guides/uxt-web-components.md)
