Skip to main content
Version: 1.7.3

Authentication and Setup

TaxBandits offers a Drop-in UI for Form W8BEN that can be seamlessly incorporated into your current systems with minimal setup.

Here are the steps to set up Drop-in UI in your application:​

1. Authentication​

To begin, you must construct a JWS using your API credentials. See how

Once JWS is constructed, you must pass it in the "Authentication: {JWS Value}" HTTP Header.

2. Get Transient Token​

Once the JWS is created, send a request to obtain the Transient Token. The request body must include the allowable origins (domains). Only requests originating from these domains will be permitted to render the W8BEN form.This helps prevent token reuse from unauthorized sources. This token will be valid for 15 minutes. You can get a new token if it expires.

Note:

We have enabled the Content Security policy with the Frame Ancestor directive in our drop-in UI. This allows only the domains specified when generating a transient token, ensuring each request is validated.

POST v2/transienttoken

Request Body​

FieldTypeDescription
Originsobject[]List your domains where you want to load the W8BEN

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. Customize W8BEN Form UI​

Call the loadFormW8BEN() method using the transient token, which must include:

  • Business details – BusinessId, PayerRef, or TIN
  • Recipient details – PayeeRef, Name, Address
  • Customization elements — Theme and redirection URLs. Click here to see what you can customize .
Note:

Before making this call, Before making this call, ensure that the corresponding business (payer) has been added to the TaxBandits API. If not, the W8BENs collected will be associated with the default business in your account. Learn More

<!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 W8BEN 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/dropinW8ben.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/dropinW8ben.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="getFormW8Ben()">
        Load Form W8Ben
        </button>
        <div id="formLoad" class="mt-10">
        <!-- Load the form -->
        </div>
    </div>
</body>
</html>

4. Load W8BEN​

Once loadFormW8BEN() is called, the script uses the transient token to securely communicate with the TaxBandits server.

The server validates the token and returns a secure, encrypted W8BEN form URL. This URL is then embedded as an iframe in your application.

Note:

All sensitive configurations (like TIN Matching, payeeRef, and theme) are encrypted and bound to the token on the server side. Even though the form is rendered in the browser, the actual payload is never exposed in the network tab or browser console, protecting against client-side tampering or inspection.

5. Recipient Submits W8BEN​

Recipients fill out and submit the W8BEN form inside the iframe. The data is securely stored by TaxBandits and never exposed to your system.

You’ll receive submission status through:

  • A webhook (if configured), or
  • A message sent from the iframe to your frontend