API Reference
My Account

About Widgets

Widgets are user interfaces to embed in an iFrame or modal window. We offer widgets for banks account linking with Plaid, debit card capture, payment acceptance, and prepaid account dashboards.

The response contains a short-lived URL with a defined expiration date.

Widget requests have the an optional widget_params parameter to specify optional parameters. Field definitions and example 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 postMessageevent - 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 user with the access code field
"widget_params" : {
        "expires_mins": 25,
        "redirect_url": "http://mydomain.com"
    }
}

"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