- Read the Quick Start guide.
- Have a parent web application in which to integrate the widget. This application must use HTTPS.
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 Payment 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.
The Add Payment Card widget enables end users to add cards not issued by Marqeta to the Marqeta platform. After you have added a card using the Add Payment Card widget, you can create Push-to-Card disbursements. A Push-to-Card disbursement is an original credit transaction (OCT) that enables end users to draw funds from your Push-to-Card funding reserve balance and send them in near real time to an external, non-Marqeta payment card. These disbursements are not linked to any purchase. For details on how to add a payment card to the Marqeta platform without using the Add Payment Card widget, see Push-to-Card Payments.
Note: The Add Payment Card widget does not allow your end user to disburse funds to a payment card. The end user must complete this task using your parent application.
The Add Payment 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.
Note: 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 Payment Card widget after the end user chooses to add a new payment card from a page in the parent web application. Each time the end user adds a new payment card to the Marqeta platform using the Add Payment Card widget, the parent website must render a new instance of the Add Payment Card widget. The Add Payment Card widget validates the end user's input, then displays a success message after adding the new payment card to the Marqeta platform.
The Add Payment Card widget applies to many use cases. For example, a contracting company that needs an alternative method to pay their non-exempt employees might use this widget to enable these employees to identify a non-Marqeta debit card as their preferred method of payment.
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.
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|
|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.
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 Add Payment Card widget is 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:
|Sandbox||Add Payment Card||https://widgets-sandbox.marqeta.com/add_payment_card|
|Production||Add Payment Card||https://widgets.marqeta.com/add_payment_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:
|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
|user_token||string||Yes||Existing user token. Send a
|success_url||string||Yes||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 card holder that the request has been successfully processed.
|display_headers||boolean||Yes||If set to false, the widget's standard headers are not displayed above the iframe.
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 payment card data in the Add Payment Card widget and clicks Submit, the widget performs a number of validations before sending the data to Marqeta's servers.
|Name on card||Yes||
The Add Payment Card widget allows the end user to make up to five attempts to submit the widget. After reaching five attempts, the widget displays an error message and must be rendered again with a new one-time authentication token. The end user must re-enter the payment card details because the input in the widget is not retained.
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.
This tutorial shows you how to customize the Add Payment Card widget and integrate it with a web application in your sandbox environment.
To customize the Add Payment Card widget for a production environment, 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 an application ID from Marqeta
Contact your Marqeta representative to obtain an application ID, which is a value used specifically for embedding the Add Payment Card widget. 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 Payment Card widget in a production scenario, this token would be the user token of whatever user is logged into your application.
Step Four: 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 "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==' \
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 Five: 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 Six: 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_payment_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:
Below is another 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 Payment Card widget, production environment