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

# Using Activate Card and Set PIN Widgets

> Integrate Marqeta's PCI-compliant Activate Card and Set PIN widgets in your application to enable your cardholders to securely activate their cards and set their PINs.

<Warning>
  **Important**\
  We are pleased to announce that the Marqeta platform is transitioning away from the Marqeta.js library and its widgets in favor of [Marqeta UX Toolkit](/developer-guides/about-ux-toolkit/) for programs based in the United States. For this reason, we are no longer adding this functionality to new US programs.

  Existing US programs are not immediately impacted, but are encouraged to migrate over to UX Toolkit as soon as possible. Programs based outside the United States are not affected by this change, but may be eligible to use UX Toolkit. Contact your Marqeta representative for more information.
</Warning>

Marqeta provides customizable widgets that enable cardholders to securely activate their cards and set their PINs in your customer web and mobile applications. You can embed these widgets inline as iframes in your web applications. The widgets comply with the Payment Card Industry Data Security Standard (PCI DSS), which defines the security and protocol standards for organizations that store, transmit, or process card data. If you have already obtained PCI Compliance certification, using the Marqeta Activate Card and Set PIN widgets in your web applications is optional.

At the end of this guide, you should understand:

* What the Activate Card and Set PIN widgets are and when you need to use them.

* How to create a customized widget to integrate with your web application.

* How the input to the widgets is validated.

<Note>
  **Note**\
  Widgets reduce your burden of achieving data security compliance by providing a PCI-compliant way to allow cardholders to perform certain actions; however, you have other responsibilities regarding data security for other elements of your cardholder experience. Contact your Marqeta representative for details.
</Note>

<h2 id="_associated_endpoints">
  Associated endpoints
</h2>

For details on how to active a card and set a PIN on the Marqeta platform without using the Activate Card and Set PIN widgets, use the following endpoints and methods:

* `POST` `/cardtransitions`

* `POST` `/pins/controltoken`

* `PUT` `/pins`

For more information, see the [Create card transition](/core-api/card-transitions/#post_cardtransitions), [Create PIN control token](/core-api/pins/#post_pins_controltoken), and [Create or update PIN](/core-api/pins/#put_pins) API references.

<h2 id="_prerequisites">
  Prerequisites
</h2>

* Read the [Core API Quick Start](/developer-guides/core-api-quick-start/).

* Obtain a user token.

* Obtain a card token that is associated with the user token, if working with the Set PIN widget.

* Have a parent web application in which to integrate the widget. This application must use HTTPS.

<h2 id="_concepts">
  Concepts
</h2>

<h3 id="_data_security_compliance">
  Data security compliance
</h3>

You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date. The process of becoming PCI DSS certified to store, transmit and process such data directly is both time consuming and expensive. The Activate Card and Set PIN widgets handle the encrypted transmission of sensitive card data, and can help you comply with some aspects of the PCI compliance burden. Marqeta is fully PCI-Service Provider Level 1 compliant, and securely handles the unencrypted, sensitive card data.

<h3 id="_available_widgets">
  Available widgets
</h3>

The Activate Card and Set PIN widgets are customizable iframes that enable the cardholder to provide sensitive card data to the Marqeta platform. When you embed a widget in your application, your servers never store, transmit, or process the card data so you are not required to be PCI DSS compliant. Embed the iframe in the parent page of your web application where you want the functionality of the widget to occur. You configure the iframe by passing query parameters in the iframe’s source URL. The Marqeta platform then processes the iframe.

<Tip>
  **Tip**\
  Embed the iframe using a web element when adding a widget to a mobile application. This applies to both Android and iOS.
</Tip>

You can integrate the following widgets:

<Steps>
  <Step>
    **Activate Card** – Allows authenticated cardholders to activate their program-specific cards.
  </Step>

  <Step>
    **Set PIN** – Allows cardholders to set their online EMV PIN code on an activated card.
  </Step>
</Steps>

Upon successful completion, the Activate Card widget renders the Set PIN widget automatically.

The Activate Card and Set PIN widgets apply to many use cases. For example, an alternative lender who leverages an authorized user model might have these widgets display as part of providing loans to businesses. The widgets would enable the business owners to activate their card, then choose their own PIN.

<Danger>
  **Warning**\
  Your application must provide a login method to authenticate the user. Widgets do not provide user authentication; they only validate that the user-entered data matches the card data on the Marqeta platform.
</Danger>

<h3 id="_widget_customization">
  Widget customization
</h3>

Before integrating widgets into your application, you must submit your customized style attributes to Marqeta. Marqeta provides the [Marqeta Widget Style Preview](https://app.marqeta.com/widgets/customize-styles.html) page as a testing ground for you to determine how you want your widgets to look.

The following styles are customizable:

| Style Category       | Attributes and Values                                                                                                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Global styles        | - Font stack, such as Helvetica, Arial, sans-serif.<br />- Font color.<br />- Font size (max 18px).<br />- Background color.                                                                                 |
| Form labels          | - Label text color.<br />- Label font size.<br />- Label font weight.<br />- Label text style.                                                                                                               |
| Headers              | - Option to show the Activate Card header.<br />- Option to show the Set PIN header.<br />- Header font size.                                                                                                |
| Button styles        | - Font stack, such as Helvetica, Arial, sans-serif.<br />- Button background color.<br />- Button font color.<br />- Hover state background color.<br />- Hover state font color.                            |
| Error message styles | Errors are displayed above the widget in a flash-message style list.<br /><br />- Font stack, such as Helvetica, Arial, sans-serif.<br />- Font color.<br />- Font size (max 18px).<br />- Background color. |
| iframe size          | - Minimum height: 120px.<br />- Minimum width: 300px.                                                                                                                                                        |

Any global styles you define are overridden by more specific style category declarations. For example, if you define a font stack in both the Global Styles category and the Button Styles category, the fonts of the Button Styles stack will apply to the buttons. Other styles are unaffected by this declaration.

<h3 id="_iframe_parameters">
  iframe parameters
</h3>

The widgets are accessible from base URLs for both the private sandbox and production environments.

Depending on your environment, use one of the following base URLs as the source of the iframe:

| Environment | Widget        | Base URL                                                                                                                                                                                               |
| ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sandbox     | Activate Card | <a href="https://widgets-sandbox.marqeta.com/activate_card" target="_blank" rel="noopener">[https://widgets-sandbox.marqeta.com/activate\_card](https://widgets-sandbox.marqeta.com/activate_card)</a> |
| Sandbox     | Set PIN       | <a href="https://widgets-sandbox.marqeta.com/set_pin" target="_blank" rel="noopener">[https://widgets-sandbox.marqeta.com/set\_pin](https://widgets-sandbox.marqeta.com/set_pin)</a>                   |
| Production  | Activate Card | <a href="https://widgets.marqeta.com/activate_card" target="_blank" rel="noopener">[https://widgets.marqeta.com/activate\_card](https://widgets.marqeta.com/activate_card)</a>                         |
| Production  | Set PIN       | <a href="https://widgets.marqeta.com/set_pin" target="_blank" rel="noopener">[https://widgets.marqeta.com/set\_pin](https://widgets.marqeta.com/set_pin)</a>                                           |

Using query parameters, you can specify the language to use when rendering the widget, as well as customize the message displayed upon successful completion of the widget’s task.

Build your iframe content for the desired widget by adding the appropriate query parameters:

| Fields                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| application\_id<br /><br />string<br /><br />Required           | The application ID for use with widgets, obtained from Marqeta in <a href="#_step_2_obtain_a_new_application_id_from_marqeta">Step 2</a>.<br /><br />**NOTE:** This value is not required when calling endpoints related to the Marqeta.js JavaScript library such as `show_pan` or `reveal_pin`, nor do you need to supply it in order to retrieve a client access token.<br /><br />**Allowable Values:**<br /><br />A valid application ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| one\_time\_token<br /><br />string<br /><br />Required          | User’s one-time authentication token, generated via `POST` at `/users/auth/onetime` in <a href="#_step_3_generate_a_one_time_user_authentication_token">Step 3</a>.<br /><br />**Allowable Values:**<br /><br />A valid one-time authentication token.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| user\_token<br /><br />string<br /><br />Required               | Existing user token. Send a `GET` request to `/users` to retrieve an existing user token.<br /><br />**Allowable Values:**<br /><br />A valid user token.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| card\_token<br /><br />string<br /><br />Conditionally required | Existing card token that is associated with the user token. Send a `GET` request to `/cards/user/{token}` to retrieve card tokens for a specific user. Required by the Set PIN widget.<br /><br />**Allowable Values:**<br /><br />A valid card token.<br /><br />**NOTE:** Only applies to the Set PIN widget.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| success\_url<br /><br />string<br /><br />Required              | HTTPS URL of the page that is loaded in the iframe upon successful completion.<br /><br />The `success_url` must use HTTPS as the protocol; most browsers do not allow HTTP content to be loaded into the iframe window. In addition, the protocol must be specified for the widget to recognize it as a valid `success_url`. This URL must not be enclosed in quotation marks, but it can be URL encoded.<br /><br />When calling a widget in an iframe, make sure the page provided does not set the X-Frame-Options to `DENY` or `SAMEORIGIN`; otherwise the iframe cannot display in modern browsers. If using the widget directly in the browser window, the redirect does not require the X-Frame-Options header.<br /><br />If the `success_url` is invalid or not provided, the widget displays a generic message informing the cardholder that the request has been successfully processed.<br /><br />**Allowable Values:**<br /><br />A valid URL. |
| display\_headers<br /><br />boolean<br /><br />Optional         | If set to `false`, the widget’s standard headers are not displayed above the iframe.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`true`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| locale<br /><br />string<br /><br />Optional                    | The language to use when rendering the widget. This parameter is a language tag composed of a language code and a country code.<br /><br />**Allowable Values:**<br /><br />`en-US` English (United States), `cs-CZ` Czech (Czechia), `de-DE` German (Germany), `es-ES` Spanish (Spain), `fr-CA` French (Canada), `fr-FR` French (France), `it-IT` Italian (Italy), `pl-PL` Polish (Poland), `pt-BR` Portuguese (Brazil), `sv-SE` Swedish (Sweden)<br /><br />**Default value:**<br />`en-US`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

<h3 id="_validation_and_error_handling">
  Validation and error handling
</h3>

The one-time user authentication token you create expires 120 minutes from when the Card Activation widget appears on-screen. The cardholder must complete the card activation during this period. After the Card Activation widget closes, the timer resets to zero to allow the cardholder another 120 minutes to set the PIN in the Set PIN widget.

After the card data has been supplied to the widget, the widget performs a number of validations before sending the data to Marqeta’s servers. The cardholder has five attempts to correctly input data in the Activate Card or the Set PIN widget. After five failed attempts, the widget displays an error message. To try another five times, the cardholder has to refresh the parent web page to force the generation of a new widget.

A cardholder might successfully activate a card using the Activate Card widget, but fail to set a PIN using the Set PIN widget. In this case, the next time the cardholder accesses the widgets, the Set PIN widget appears without displaying the Activate Card widget again.

<Danger>
  **Warning**\
  There is no way for the widget to inform the parent web page in the event of an error. If the widget encounters an error, the cardholder must refresh the parent web page. Consider providing instructions to the cardholder on how to do this.
</Danger>

**Activate Card validation**

The following validations are performed on the data entered in the widget when the cardholder clicks or taps **Activate Card**:

* PAN has been entered in the widget.

* PAN is a valid card number.

* CVV has been entered in the widget.

* CVV is 3 or 4 characters in length.

* CVV is a numeric value.

If successful, the failure count and the timer are reset to 0, and the Activate Card widget automatically renders the Set PIN widget.

**Set PIN validation**

The following validations are performed on the data entered in the widget when the cardholder clicks or taps **Set PIN**:

* PIN does not contain consecutive ascending or descending values, such as 1-2-3-4 or 9-8-7-6.

* PIN is not a single digit repeated four times, such as 2-2-2-2.

* PIN is not one of the most common PINs chosen by cardholders.

* PIN confirmation value matches the PIN value.

If successful, the page specified by the `success_url` parameter is loaded.

<h2 id="_tutorial">
  Tutorial
</h2>

This tutorial walks you through how to customize the Activate Card widget and integrate it with a web application in your private sandbox environment.

The Activate Card and Set PIN widgets are not supported in the public sandbox.

<h3 id="_step_1_define_the_widget_style_attributes">
  Step 1 — Define the widget style attributes
</h3>

Go to the [Marqeta Widget Style Preview](https://app.marqeta.com/widgets/customize-styles.html) page to configure and preview the widget’s styles. Choose attributes that match your web application. Send the finalized styles to Marqeta for implementation when you are ready to integrate a widget into your production environment.

<h3 id="_step_2_obtain_a_new_application_id_from_marqeta">
  Step 2 — Obtain a new application ID from Marqeta
</h3>

Contact your Marqeta representative to obtain an application ID, which is a value used specifically for embedding the Activate Card and Set PIN widgets. You must use the same application ID for both widgets. This value is typically provided when you begin working with Marqeta.

<h3 id="_step_3_generate_a_one_time_user_authentication_token">
  Step 3 — Generate a one-time user authentication token
</h3>

Configure your web application to send a `POST` request to `/users/auth/onetime` to generate a one-time user authentication token for the logged-in user. The single-use access token you create for the logged-in user is valid for one request only, and expires five minutes after it is generated. See the [Create single-use token](/core-api/users/#post_users_auth_onetime) section of the [Users](/core-api/users/) page for more information about this endpoint.

The following is an example of a cURL request that generates a one-time user authentication token:

```sh cURL lines wrap theme={null}
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic dXNlcjM5MDQxNTM2ODY0MTY4OjRhN2VkNDlhLWZjOTctNDdmNy04NmY0LTUxN2VjZTE1ZGY5ZQ==' \
-d '{
    "user_token": "bc381ddf-b8c9-47b5-a724-4ae71f1aad7d"
  }' \
'https://your_payments_instance.com/v3/users/auth/onetime'
```

<Danger>
  **Warning**\
  After the one-time token is redeemed to render the parent web page, it cannot be reused. If the widget times out or the parent web page is refreshed by the cardholder, a new one-time token must be generated and passed to the iframe.
</Danger>

<h3 id="_step_4_add_query_parameters_to_the_iframe">
  Step 4 — Add query parameters to the iframe
</h3>

Build the iframe content for the widget by adding the appropriate query parameters from the table in the "iframe parameters" section.

<h3 id="_step_5_embed_the_iframe_in_the_parent_website">
  Step 5 — Embed the iframe in the parent website
</h3>

Embed the iframe in the parent website, using the following as the iframe’s source: [https://widgets-sandbox.marqeta.com/activate\_card](https://widgets-sandbox.marqeta.com/activate_card). Since the iframe is requesting an HTTPS domain, the parent website URL must also use the HTTPS protocol.

When completed, the HTML for the iframe should resemble the following:

`<iframe src="https://widgets-sandbox.marqeta.com/activate_card?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&application_id=33333333-3333-3333-3333-3333&success_url=https://yoursite.com/success_widget.html&display_headers=false"></iframe>`

<h2 id="_samples">
  Samples
</h2>

Below are samples of iframes you can create by following the tutorial’s steps. In each of these samples, a success URL is specified and the headers are disabled. The base URL reflects whether the iframe is used in a private sandbox or a production environment.

**Activate Card widget, private sandbox environment**

`<iframe src="https://widgets-sandbox.marqeta.com/activate_card?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&application_id=33333333-3333-3333-3333-3333&success_url=https://yoursite.com/success_widget.html&display_headers=false"></iframe>`

**Activate Card widget, production environment**

`<iframe src="https://widgets.marqeta.com/activate_card?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&application_id=33333333-3333-3333-3333-3333&success_url=https://yoursite.com/success_widget.html&display_headers=false"></iframe>`

**Set PIN widget, private sandbox environment**

`<iframe src="https://widgets-sandbox.marqeta.com/set_pin?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&card_token=44444444-4444-4444-4444-444444444444&application_id=33333333-3333-3333-3333-3333&success_url=https://yoursite.com/success_widget.html&display_headers=false"></iframe>`

**Set PIN widget, production environment**

`<iframe src="https://widgets.marqeta.com/set_pin?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&card_token=44444444-4444-4444-4444-444444444444&application_id=33333333-3333-3333-3333-3333&success_url=https://yoursite.com/success_widget.html&display_headers=false"></iframe>`


## Related topics

- [PCI Compliance Overview](/docs/developer-guides/pci-compliance-landing-page.md)
- [PINs](/docs/core-api/pins.md)
- [2022 Release Notes](/docs/developer-guides/release-notes-2022.md)
- [Errors](/docs/core-api/errors.md)
- [Working with UX Toolkit Web Components](/docs/developer-guides/uxt-web-components.md)