Using the Add Source Card Widget

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

Marqeta provides a customizable Add Source Card widget that you can integrate with your website or mobile application as part of an instant funding transfer solution. Instant funding increases user engagement by making funds available to your end users within seconds, regardless of the time or day. Faster, secure access to funds leads to increased engagement and user spend. Until now, end users funding a new account could either set up direct deposit (and wait to receive funds through their payroll) or use ACH transfer (which can take three to five days to appear in the new bank account). Weekends or holidays could also occasionally impact business operations. All these delays could cause end users to drop off and not use their new account. This widget allows users to enter their information about an external card that was not issued by Marqeta. The widget then validates and delivers these details to the Marqeta platform. Your end user can pull funds from the external card as an instant funding transfer (also known as a pull-from-card transfer) using your web or mobile application. You can embed the Add Source Card widget inline as an iframe in your web or mobile applications. The widget complies 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 this widget in your web or mobile applications is optional. At the end of this guide, you should understand:

What the Add Source Card widget is and when you need to use it.
How to create a customized Add Source Card widget to integrate with your web application.
How the input to the widget is validated.

Note
The Add Source Card widget reduces your burden of achieving data security compliance by providing a PCI-compliant way to allow end users to perform certain actions; however, you have additional responsibilities regarding data security for other elements of your end-user experience. Contact your Marqeta representative for details.

Associated endpoint

To add an external payment card to the Marqeta platform without using the Add Source Card widget, use the following endpoint and method:

POST /moneymovement/sourcecards

For more information, see the Add external card API reference.

Prerequisites

Read the Core API Quick Start.
Have a parent web application in which to integrate the widget. This application must use HTTPS.

Concepts

Data security compliance

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 Add Source Card widget handles the encrypted transmission of sensitive card data, and can help you comply with some aspects of the PCI compliance burden. Marqeta is PCI-Level 1 compliant, and securely handles the unencrypted, sensitive card data.

Instant funding or “pull-from-card” transfers

The Add Source Card widget enables your end users to add external cards not issued by Marqeta to the Marqeta platform. After you have added a card using the Add Source Card widget, you can create instant funding transfers (also known as pull-from-card transfers). An instant funding transfer is an Account Funding Transaction (AFT) that enables end users to pull funds from their external, non-Marqeta debit/prepaid card and send them within seconds to their Marqeta debit or prepaid card. These transfers are not linked to any purchase.

Note
The Add Source Card widget does not allow your end user to transfer funds to a payment card. The end user must complete this task using your parent application.

Widget implementation

The Add Source Card widget is a customizable iframe that enables the end user to provide sensitive data to the Marqeta platform. When you embed a widget in your application, your servers never store, transmit, or process the 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, then the Marqeta platform processes the iframe.

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

Your parent web application should render the Add Source Card widget after the end user chooses to add a new external card from a page in the parent web application. Each time the end user adds a new external card to the Marqeta platform using the Add Source Card widget, the parent website must render a new instance of the Add Source Card widget. The Add Source Card widget validates the end user’s input, then displays a success message after adding the new external source card to the Marqeta platform. The Add Source Card widget applies to many use cases that securely facilitate faster access to deposited funds. Faster access to funds leads to increased engagement and spend by your end users.

Warning
Your application must provide a login method to authenticate the end user. Widgets do not provide user authentication; they only validate that the user-entered data matches the data on the Marqeta platform.

Widget customization

Before integrating widgets into your web or mobile 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:

Style Category	Attributes and Values
Global styles	- Font stack, such as Helvetica, Arial, sans-serif. - Font color. - Font size (max 18px). - Background color.
Form labels	- Label text color. - Label font size. - Label font weight. - Label text style.
Headers	- Option to show the widget header. - Header font size.
Button styles	- Font stack, such as Helvetica, Arial, sans-serif. - Button background color. - Button font color. - Hover state background color. - Hover state font color.
Error message styles	Errors are displayed either above the widget in a flash-message style list or underneath the input boxes to which they apply. - Font stack, such as Helvetica, Arial, sans-serif. - Font color. - Font size (max 18px). - Background color.
iframe size	- Minimum height: 120px. - 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.

iframe parameters

The Add Source Card widget is 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	Add Source Card	https://widgets-sandbox.marqeta.com/add_external_card
Production	Add Source Card	https://widgets.marqeta.com/add_external_card

Using query parameters, you can customize the message displayed upon successful completion of the widget’s task. Build your iframe content for the widget by adding the appropriate query parameters:

Fields	Description
application_id string Required	The application ID for use with widgets, obtained from Marqeta in Step 2. 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. Allowable Values: A valid application ID.
one_time_token string Required	User’s one-time authentication token, generated via `POST` at `/users/auth/onetime` in Step 4. Allowable Values: A valid one-time authentication token.
user_token string Required	Existing user token. Send a `GET` request to `/users` to retrieve an existing user token in Step 3. Allowable Values: A valid user token.
success_url string Required	HTTPS URL of the page that is loaded in the iframe upon successful completion. 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. 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. 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. Allowable Values: A valid URL.
display_headers boolean Required	If set to `false`, the widget’s standard headers are not displayed above the iframe. Allowable Values: `true`, `false` Default value: `true`

Validation and error handling

The one-time user authentication token you create expires 120 minutes from when the widget appears on-screen. The end user must complete the widget’s task during this period. After the end user enters the external source card data in the Add Source Card widget and selects Submit, the widget performs a number of validations before sending the data to Marqeta’s servers.

Field Name	Required?	Validations
Card number (PAN)	Required	- Cannot contain spaces. - 19 char max - 12 char min - Must match a recognized format. WARNING: Not all cards are eligible for AFT instant funding transfers. The widget will inform the end user if the card number entered cannot be used to transfer funds in this way.
CVV	Required	3 char max
Expiration date	Required	Format: MMyy
Postal code	Required	- 10 char max - Must contain only alphanumeric characters.
Birth date	Required	Format: yyyy-MM-dd

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 end user must refresh the parent web page. Consider providing instructions to the end user on how to do this.

Tutorial

This tutorial shows you how to customize the Add Source Card widget and integrate it with a web application in your private sandbox environment. To customize the Add Source Card widget for a production environment, see the Sample section below.

Step 1 — Define the widget style attributes

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.

Step 2 — Obtain an application ID from Marqeta

Contact your Marqeta representative to obtain an application ID, which is a value used specifically for embedding the Add Source Card widget. This value is typically provided when you begin working with Marqeta.

Step 3 — Obtain a user token

Obtain an existing user token by sending a GET request to /users.

Note
If you were using the Add Source Card widget in a production scenario, this token would be the user token of whatever user is logged into your application.

Step 4 — Generate a one-time user authentication token

Configure your 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 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:

cURL

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'

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 end user, a new one-time token must be generated and passed to the iframe.

Step 5 — Add query parameters to the iframe

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

Step 6 — Embed the iframe in the parent website

Embed the iframe in the parent website, using the following as the iframe’s source: https://widgets-sandbox.marqeta.com/add_external_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/add_external_card?application_id=11111111-1111-1111-1111-111111111111&one_time_token=22222222-2222-2222-2222-222222222222&user_token=33333333-3333-3333-3333-333333333333&display_headers=true"></iframe>

Sample

Below is an iframe you can create by following the tutorial’s steps. In this sample, a success URL is specified and the headers are disabled. The base URL reflects that the iframe is used in a production environment.

Add Source Card widget, production environment

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

Guides

​Associated endpoint

​Prerequisites

​Concepts

​Data security compliance

​Instant funding or “pull-from-card” transfers

​Widget implementation

​Widget customization

​iframe parameters

​Validation and error handling

​Tutorial

​Step 1 — Define the widget style attributes

​Step 2 — Obtain an application ID from Marqeta

​Step 3 — Obtain a user token

​Step 4 — Generate a one-time user authentication token

​Step 5 — Add query parameters to the iframe

​Step 6 — Embed the iframe in the parent website

​Sample

​Add Source Card widget, production environment

Associated endpoint

Prerequisites

Concepts

Data security compliance

Instant funding or “pull-from-card” transfers

Widget implementation

Widget customization

iframe parameters

Validation and error handling

Tutorial

Step 1 — Define the widget style attributes

Step 2 — Obtain an application ID from Marqeta

Step 3 — Obtain a user token

Step 4 — Generate a one-time user authentication token

Step 5 — Add query parameters to the iframe

Step 6 — Embed the iframe in the parent website

Sample

Add Source Card widget, production environment