About Widgets

Widget requests

Widget requests have the optional widget_params parameter to specify optional parameters. Field definitions and examples below.

• expires_mins: number of minutes the widget URL is valid; bank account widgets are 59 minutes, other widgets default to 15 minutes.
• redirect_url: URL location to redirect after payment acceptance or debit card added.
• target_origin_url: URL location to reference in a postMessage event - implementation details below. Not applicable to bank account widgets due to iFrame element restrictions.
• access_code: String value the user must enter to view widget content.
• access_code_phrase: String value presented to the user with the access code field.

Widget Params Example with Redirect

"widget_params": {
    "expires_mins": 25,
    "redirect_url": "http://mydomain.com"
}

Widget Params Example with Target Origin URL

"widget_params": {
    "expires_mins": 25,
    "target_origin_url": "http://mydomain.com"
}

Widget Styling

Our onboarding team can configure the widget style to have a white or black background with visible field labels or hidden labels.

Handling a postMessage event

Now available in the CARD and BANK account widget. If the parent window would prefer a postMessage event from the child frame, include the target_origin_url parameter in the widget_params and omit the redirect_url.

For CARD, a sample JSON message posted to the target origin URL is:

{"source": "IC", "type": "CARD", "result": "SUCCESS", "widget_id": "<widget_id>"}

For BANK, a sample JSON message would resemble:

{"source": "IC", "type": "BANK", "result": "SUCCESS", "widget_id": "<widget_id>", "account_id": "<account_id>"}

Or in the event of an error:

{"source": "IC", "type": "BANK", "result": "ERROR", "widget_id": "<widget_id>", "error_code": "<error_code>"}

Handling a URL Redirect

The BANK account widget will append the following parameters to the redirect_url:

• widgetId
• accountId - Only if an account record was created.
• errorCode - Only if an error occurred during the Plaid Link process.
• rtpStatus - Only if an account record was created.