Skip to main content
Version: 1.7.3

Drop-In UI — How It Works

The Drop-In UI is a ready-made W-9/W-8 form interface provided by TaxBandits that you embed directly inside your application. It is fully customizable using JavaScript and CSS, allowing you to match your product's branding exactly — including fonts, colors, button styles, and label text.

Unlike URL-based collection methods, Drop-In UI does not redirect recipients to an external page. The form loads within your application's own frame, giving you full control over the experience.

When to use Drop-In UI​

  • You need the form to visually match your product — the same design system, same colors, same typography.
  • You want to avoid the appearance of third-party redirects during a sensitive onboarding step.
  • Your platform has strict Content Security Policy (CSP) requirements that you manage centrally.

Steps to configure​

Drop-In UI requires a short authentication setup before the form can be loaded. The process has four steps:

  1. Retrieve your API credentials (User Token, Client ID, Client Secret) from the Developer Console under Settings → Credentials.

  2. Construct a JWS (JSON Web Signature) token using your credentials. The JWS uses the HS256 algorithm and encodes your Client ID as the issuer, subject, and audience, along with the issued-at timestamp in Unix epoch format.

  3. Exchange the JWS for a transient token by calling the Drop-In UI authentication endpoint. Include the allowed origin domains in the request body — the Content Security Policy will only permit the form to load on these domains.

  4. Use the transient token to initialize and render the Drop-In UI in your application. The token expires in 15 minutes; request a new one when it expires.

The allowed origins you declare when obtaining the transient token are enforced by the Content Security Policy frame-ancestor directive. The form will not load on any domain not included in this list.

Customizable elements​

Once initialized, the following visual elements of the form page can be customized:

Input fields
  • Font color
  • Border color
  • Focus border color
  • Border radius
Typography & labels
  • Label color
  • Hyperlink color
  • Heading color
  • Subheading color
  • Body paragraph color
  • Help text color
Buttons
  • Primary color
  • Secondary color
  • Font color
Other
  • Checkbox background color

TIN Matching with Drop-In UI​

To enable TIN Matching for the Drop-In UI, set IsTINMatching to TRUE in the JavaScript request. Once enabled, TIN validation will be triggered automatically during form submission.

Receiving submission events​

Because the Drop-In UI is embedded within your application, you can receive real-time submission notifications via webhooks (configured separately) or by listening for postMessage events from the embedded frame.