Using Account Capture Widgets

Note: This feature is currently in beta and subject to change. To learn more about the Beta program for this feature, contact your Marqeta representative.

Marqeta provides customizable widgets that you can integrate with your website or mobile application as part of a bill payment or debt consolidation solution. These widgets allow users to enter information about their account with a biller, such as the account number and the account holder name, in order to create or update a biller account association.

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 these widgets in your web applications is optional.

At the end of the guide, you should understand:

  • What the Add Account, Bill Payments, and Update Account 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: Widgets reduce 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.   

Prerequisites

  • Read the Quick Start guide.
  • 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 card holder'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 Account and Update Account widgets handle 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. 

Biller account associations

The Add Account, Bill Payments, and Update Account widgets create or update a biller account association. A biller account association establishes which biller on the Marqeta platform the end user wants to make payments to; it also enables balance updates when a biller account is connected. For details on how to create an association between a biller and an end user on the Marqeta platform without using the Add Account widget, see Create biller account association.

Available widgets

The Add Account, Bill Payments, and Update Account widgets are customizable iframes that enable 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.

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

You can integrate the following widgets:

  1. Add Account – Allows your end users to create a new biller account association on the Marqeta platform. They then can pay this biller account using your parent web application.
  2. Bill Payments – Lists all failed bill payment attempts.
  3. Update Account – Allows end users to update a biller account association by correcting the biller account details related to a failed bill payment.

Your parent web application should render the Add Account widget after the end user chooses to add a new biller manually from a page in the parent web application. The widget can pre-populate certain fields such as the account holder name if the end user has already paid bills with the Marqeta platform. Each time the end user adds an account to the Marqeta platform using the Add Account widget, the parent website must render a new instance of the Add Account widget. The Add Account widget validates the end user's input, then displays a success message after adding the new account.

The Bill Payments widget displays a list of all payments made by the end user that failed to process. For each payment, the widget displays the biller name, transaction amount, and error description, as well as a link to update the account details. After the end user makes a selection from the Bill Payments widget, the Bill Payments widget renders the Update Account widget automatically.

Using the Update Account widget, the end user can modify account details when a payment does not complete successfully. All widget fields are pre-populated, with the fields that the end user must update marked as an error. After the end user modifies the details of the failed payment in the Update Account widget, the Update Account widget renders the Bill Payments widget again. Failed payments remain in the Bill Payments widget until the end user successfully updates the payment account details in the Update Account widget, then pays the bill again. The widget does not automatically resubmit the failed payments.

The Add Account, Bill Payments, and Update Account widgets apply to many use cases. For example, an alternative lender who offers loans as a debt consolidation strategy might have these widgets display as part of identifying which creditors the end user wants to pay off.

Note: 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 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 Add Account header.
  • Option to show the Bill Payments header.
  • Option to show the Update Account 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 above the widget in a flash-message style list.
  • 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 widgets are accessible from base URLs for both the sandbox and the 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:

Parameter Type Required? Description
application_id string Yes The application ID for use with widgets, obtained from Marqeta in Step Two.
one_time_token string Yes User's one-time authentication token, generated via POST at /users/auth/onetime in Step Five.
user_token string Yes Existing user token. Send a GET request to /users to retrieve an existing user token in Step Three.
biller_token string Yes, if Add Account or Update Account widget Existing biller token that you want to associate with the user token.

The biller_token is obtained differently, depending on whether you are building the iframe for an Add Account or an Update Account widget:
  • For the Add Account widget, send a GET request to /billconfigurations/billers to retrieve all billers and search by name.
  • For the Update Account widget, send a GET request to /billconfigurations/accounts/?user_token={user_token} to retrieve biller tokens for a specific user.
Note: Only applies to the Add Account or Update Account widgets.
account_token string Yes, if Update Account widget Existing account token, created as part of adding a new account.
Note: Only applies to the Update Account widget.
display_headers boolean Yes If set to false, the widget's standard headers are not displayed above the iframe.
Default: true
locale string No The language to use when rendering the widget. This parameter is a language tag composed of a language code and a country code. The following language tag values are supported:
  • en-US
  • fr-CA
Default: en-US

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 Bill Payment widget closes, the timer resets to zero to allow the end user another 120 minutes to update the account details in the Update Account widget.

After the end user enters the account data in the Add Account or Update Account widget and clicks Submit, the widget performs a number of validations before sending the data to Marqeta's servers. 

Field Name Required? Validations
Account name Yes
  • Maximum of 255 char.
  • Cannot contain special characters.
Account number Yes
  • Cannot contain spaces.
  • Maximum of 50 char.
  • Must match a recognized format.
First name Yes
  • Must match the account's stored value.
  • Maximum of 40 char.
  • Cannot be a number.
Last name Yes
  • Must match the account's stored value.
  • Maximum of 40 char.
  • Cannot be a number.
Birth date Yes
  • Must match the account's stored value.
  • Must be in format: yyyy-MM-dd.
Phone number No
  • Must match the account's stored value.
  • Must be in format: 510-555-1212.
Address No
  • Must match the account's stored value.
  • Maximum of 255 char.
City Yes
  • Must match the account's stored value.
  • Maximum of 255 char.
State Yes
  • Must match the account's stored value.
  • Maximum of 2 char.
Postal code No
  • Must match the account's stored value.
  • Maximum of 10 char.
  • Must contain only alphanumeric characters.

Note: 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 Account widget and integrate it with a web application in your sandbox environment; it assumes that the end user has not already created an account on the Marqeta platform.

To customize the Bill Payments and Update Account widgets, see the Samples section.

Step One: 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 Two: Obtain a new application ID from Marqeta

Contact your Marqeta representative to obtain an application ID, which is a value used specifically for embedding the Add Account, Bill Payments, and Update Account widgets. You must use the same application ID for all three widgets. This value is typically provided when you begin working with Marqeta.

Step Three: Obtain a user token

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

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

Step Four: Obtain a biller token

Obtain a biller token that is associated with the user token from Step Three by sending a GET request to /billconfigurations/billers?name=BillerNameHere.

Note: If you were using the Add Account widget in a production scenario, this would be the biller account with which you are creating an association.

Step Five: Generate a one-time user authentication token

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:

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'

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

Step Seven: Embed the iframe in the parent website

Embed the iframe in the parent website, using the following as the iframe's source: https://widgets-sandboxi.marqeta.com/add_account. 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_account?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&biller_token=33333333-3333-3333-3333-333333333333&application_id=44444444-4444-4444-4444-4444&display_headers=false></iframe>


Samples

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

Add Account widget, sandbox environment

<iframe src="https://widgets-sandbox.marqeta.com/add_account?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&biller_token=33333333-3333-3333-3333-333333333333&application_id=44444444-4444-4444-4444-4444&display_headers=false>

Add Account widget, production environment

<iframe src="https://widgets.marqeta.com/add_account?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&biller_token=33333333-3333-3333-3333-333333333333&application_id=44444444-4444-4444-4444-4444&display_headers=false>

Bill Payments widget, sandbox environment

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

Bill Payments widget, production environment

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

Update Account widget, sandbox environment

<iframe src="https://widgets-sandbox.marqeta.com/update_account?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&account_token=33333333-3333-3333-3333-333333333333&application_id=44444444-4444-4444-4444-4444&display_headers=false> 

Update Account widget, production environment

<iframe src="https://widgets.marqeta.com/update_account?one_time_token=11111111-1111-1111-1111-111111111111&user_token=22222222-2222-2222-2222-222222222222&account_token=33333333-3333-3333-3333-333333333333&application_id=44444444-4444-4444-4444-4444&display_headers=false>