Using Activate Card and Set PIN Widgets

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.

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.

You can integrate the following widgets:

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.

Before integrating widgets into your application, you must submit your customized style attributes to Marqeta. Marqeta provides the Marqeta Widget Style Preview page as a testing ground for you to determine how you want your widgets to look.

The following styles are customizable:

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.

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:

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:

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.

Activate Card validation

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

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:

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

Go to the Marqeta Widget Style Preview 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.

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.

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 Return single-use token section of the 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:

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

Embed the iframe in the parent website, using the following as the iframe’s source: 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>