Skip to main content
Version: 1.7.3

Authentication and Setup

Our Form W8BEN drop-in UI can be effortlessly incorporated into your current systems with minimal setup. This option provides you with the flexibility to tailor the W8BEN page completely to your specific preferences using HTML, JavaScript, and Bootstrap.

Here are the steps to setup Drop-in UI in your application:

  1. Construct Authentication Token (JWS)
  2. Get Transient Token
  3. Customize UI
  4. Load W-8 BEN
Drop In W8BEN Authentication

1. Construct Authentication Token (JWS)​

You must construct a JWS to get a Transient Token.

  • To Construct JWS, you must retrieve the API keys (User Token, Client ID, Client Secret) in the sandbox console.

API Credentials

  • The JWS consists of 3 parts, as given below:

    Header:

    {
        "alg": "HS256", /*Algorithm = HS256*/
        "typ": "JWT" /*Type = JSON Web Token (JWT)*/
    }

    Payload:

    {
        "iss": "968a9c78dae29a29",  /*Issuer: Client ID retrieved from the console site*/
        "sub": "968a9c78dae29a29",  /*Subject: Client ID retrieved from the console site*/
        "aud": "a574b75f18b24fc09f9039ffb5cb08f3", /*Audience: User Token retrieved from the console site*/
        "iat": 1516239022 /*Issued at: Number of seconds from Jan 1 1970 00:00:00 (Unix epoch format)*/
    }

    Signature:

        HMACSHA256(
        base64UrlEncode(header) + "." +
        base64UrlEncode(payload),
        siqHfLy59g3UHxrb5gjxg  /*Client Secret retrieved from the console site*/

    )

Sample JWS

    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOi
    I5NjhhOWM3OGRhZTI5YTI5Iiwic3ViIjoiOTY4YTljNzhkYWUyOWEyOSIsImF1
    ZCI6ImE1NzRiNzVmMThiMjRmYzA5ZjkwMzlmZmI1Y2IwOGYzIiwiaWF0IjoxN
    TE2MjM5MDIyfQ.HNQznxlPyVt62kyUeVwtk1-uzm1uDWH4NBDLShA6Ac0

2. Get Transient Token​

Once the JWS is constructed, send an API request to obtain the transient token. In order to obtain a transient token, you must pass the JWS in the "Authentication: {JWS Value}" HTTP Header and the Request Body must include the allowable origins (domains) to load the W8BEN UI. This transient token expires in 15 minutes. If it's expired, you can get another token.

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 UI​

Customize the JS for the Form W8BEN page (secure URL) with your own branding elements as you prefer. Click here for detailed information about the components you can customize.

<!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>
    <script src="https://js.taxbandits.io/Sprint/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 you have completed customizing the W8BEN page, integrate it into your application by setting up an HTML element with the unique ID formLoad. This is where the W8BEN page will be loaded.