Skip to main content
Version: 2.0

Drop-in UI - Authentication & Setup

The Drop-in UI is a ready-made, branded interface you embed directly in your application to collect W-9 forms from recipients. It can be integrated into your platform with minimal development effort while maintaining your branding and security requirements.

When to use​

  • 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.

Setting up Drop-in UI in your application​

1. Authenticate​

Generate a JWS token using your TaxBandits API credentials. Include it in the Authentication header of every request: See how

Authentication: {JWS Value}

2. Generate a Transient Token​

Before the form can load, you need a Transient Token. This token authorizes the Drop-in UI session, restricts rendering to domains you specify, and expires after 15 minutes. You can regenerate it at any time.

For additional security, TaxBandits enforces a Content Security Policy (CSP) using the frame-ancestors directive. Only domains specified during token generation can render the embedded form.

POST v2/transienttoken

Request Body​

FieldTypeDescription
Originsobject[]List your domains where you want to load the W-9

Request JSON:​

{
    "Origins": [
        "https://developer.taxbandits.com/",
        "https://{yourdomain.com}/"
    ]
}

Response Body​

FieldTypeDescription
StatusCodenumberReturns the HTTP status codes like 200,300 etc.
StatusNamestringName of the status code
StatusMessagestringDetailed status message
TransientTokenstringA short-term token that lasts 15 minutes
TokenTypestringType of the token provided
ExpiresInnumberThe expiry time of the token
Errorsobject[]Shows detailed error information
IDstringReturns the validation error Id
NamestringName of the validation error
MessagestringDescription of the validation error

Response JSON:​

{
    "StatusCode": 200,
    "StatusName": "OK",
    "StatusMessage": "Successful API call",
    "TransientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1ODYxYTIwMzY5MWI0NDAwODk1OWU2NTBjYWNlN2ViZiIsImRyb3B1aWQiOiIzOGI5ZTllZS0wMGE1LTQ3N2MtYTExMS00NDM0YTIyYTg2ZWMiLCJleHAiOjE3MjE2MzI1NzcsImlhdCI6MTcyMTYzMTY3NywiaXNzIjoiaHR0cHM6Ly9vYXV0aC5zcGFuc3ByaW50LmNvbS92Mi8iLCJzdWIiOiI4NWY2OTJkN2RhYTEwNmJiIn0.L1YWjLpur2IWvE-0et9PlApBxqXpypG_bPYM0DEpmVg",
    "TokenType": "Bearer",
    "ExpiresIn": 900,
    "Errors": null
}

Curl:​

curl --location "https://testoauth.expressauth.net/v2/transienttoken" --header "authentication: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4NWY2OTJkN2RhYTEwNmJiIiwic3ViIjoiODVmNjkyZDdkYWExMDZiYiIsImF1ZCI6IjU4NjFhMjAzNjkxYjQ0MDA4OTU5ZTY1MGNhY2U3ZWJmIiwiaWF0IjoxNzIwNTE5MzgwfQ.GzHXe7-qgrbMYIrHz783uPkHDh3P_1kwtXADwGsZjF0" --header "Content-Type: application/json" --data "{\"Origins\": [\"https://developer.taxbandits.com/\"]}"

3. Configure the Form​

With the Transient Token in hand, configure the WHCertificate form using the loadFormWH() method. You can pass:

  • Business details — BusinessId, PayerRef, or TIN
  • Recipient details — PayeeRef, Name, Address
  • TIN Matching — Set IsTINMatching to TRUE to enable.
  • Customization — Theme settings and redirect URLs. See Customization options.

Before making this call, ensure the corresponding business/payer has already been added to TaxBandits through the Business endpoint. If payer details are not provided, any W-9 forms collected through WhCertificate will be associated with the default business in your account.

4. Add the Drop-In UI Script​

Include the TaxBandits Drop-In UI script in your application.

<!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Drop-in UI</title>
      <!-- 
          This JavaScript file loads the prebuilt W-9 form drop-in component 
          from the TaxBandits sandbox server for testing and development. -->
      <script src="https://js.taxbandits.io/SB/Web/Dropin/v1.0.0/dropinW9.js"></script>
      <!-- 
          For Production, REPLACE the above sandbox script URL 
          with the production script below. -->
      <!-- <script src="https://js.taxbandits.io/Web/Dropin/v1.0.0/dropinW9.js"></script> -->
  </head>
  <body>
    <div class="container">
        <div id="request-container" class="drpHide">
        <!-- load the input fields inside the container -->
        </div>

        <button id="submit-button" class="btn btn-primary drpHide" onclick="getFormW9()">
        Load Form W9
        </button>
        <div id="formLoad" class="mt-10">
        <!-- Load the W9 form -->
        </div>
    </div>
</body>
</html>

5. Load the WhCertificate Form​

When loadFormWH() is executed, the Drop-In UI uses the Transient Token to securely communicate with TaxBandits servers.

During this process:

  • The token is validated.
  • An encrypted form URL is generated.
  • The form is rendered inside an iframe.
  • Sensitive configuration values remain encrypted and are never exposed in browser developer tools.

All sensitive configurations, such as TIN Matching, PayeeRef, and theme settings, are encrypted and securely bound to the transient token on the server side. Although the form is rendered in the browser, the actual payload is not exposed in the network tab or browser console. This helps protect the form against client-side tampering or inspection.

6. Recipient Submission​

Once the form loads, the recipient completes and submits their W-9 directly within your application. TaxBandits stores the completed form securely. The submitted data is not passed back through the browser.

7. Receive Submission Updates​

After the recipient submits the form, you can track the submission status through:

  • Webhook — Receive real-time status updates when the form is submitted.
  • Iframe message — Receive a frontend message from the embedded iframe to update the user experience immediately.