Initialising the Widget

After successfully getting your OAuth token, your server side will need to request a User Session Token.

User Session Token

The User Session Token is used to initialise the widget at the point that you want your customers to see it. The User Session Token is retrieved from the User Session Endpoint. Encrypted within the User Session Token is all the information required by the Widget to configure itself. Each User Session Token is unique and has a limited lifetime - it will expire after 15 minutes.  

Request a User Session Token

Initializing the DirectID Widget requires a User Session Token, which you can request from the API’s User Session Endpoint. You will need to provide a valid OAuth Token within the header for your request.  We recommend that you check out our sample apps for fully implemented examples of this process.  The API will respond with a User Session JSON Object containing a reference and token.

 * The AcquireUserSessionToken() method here shows how to make an HTTP request with OAuth token in its authentication header, 
 * send the request to the API endpoint, receive the response and extract user session token from the response.

/// <summary>
/// Queries <paramref name="apiEndpoint"/> with an http request
/// authorized with <paramref name="authenticationToken"/>.
/// </summary>
private static async Task<string> AcquireUserSessionToken(
    string authenticationToken,
    Uri apiEndpoint)
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", authenticationToken);

    var response = await httpClient.GetAsync(apiEndpoint);
    if (!response.IsSuccessStatusCode)
        throw new InvalidOperationException(
            "Unable to acquire access token from endpoint: " + apiEndpoint +
            ".  Please check your settings from Direct ID.");

    var userSessionResponse = await response.Content.ReadAsAsync<UserSessionResponse>();
    return userSessionResponse.token;


 *Here’s the same functionality of acquiring user session token implemented in Java.

 * Queries <paramref name="apiEndpoint"/> with an http request
 * authorized with <paramref name="authenticationToken"/>.
 * @param client
 * @param api
 * @param acquiredToken
 * @return
public String acquireUserSessionToken(DefaultHttpClient client, String api, String acquiredToken) {
    HttpGet request = new HttpGet(api);
    request.setHeader("Authorization", String.format("Bearer %s", acquiredToken));
    try {
        return extractTokenFromResponse(client.execute(request).getEntity().getContent());
    } catch (Exception e) {
        throw new RuntimeException("Unable to get the Api Token");


 * Our sample PHP web app named php_sample_web_app contains userSessionExample.php file that has everything you need to acquire a user session token if you want to do it in PHP. 
 * The sample app uses cURL for HTTP and also contains functionality to process response JSON message to extract user access token.

//Get User Token using cURL, an oAuthToken must be supplied (see returnOAuthToken() in previous example
function returnUserToken($oAuthToken){
    global $apiUserSessionEndpoint;
    if($apiUserSessionEndpoint != null){
        //Make API request
        $apiResponse = makeAPIRequest($apiUserSessionEndpoint, $oAuthToken);   
        //Handle response
        if($apiResponse != false){
            $jsonResponse = json_decode($apiResponse);
            if(json_last_error() == JSON_ERROR_NONE) {                       
                //Build and return user token
                $userToken = new UserToken();            
                $userToken->token = $jsonResponse->{'token'};
                $userToken->reference = $jsonResponse->{'reference'};
                return $userToken;


Your server side will pass on the user session token to the DirectID Widget to initialize it.


Initialising the Widget


Initializing and using the DirectID widget is a client side operation and for this you will use HTML and CSS.

The following steps will guide you through setting up the required JavaScript and CSS libraries which the Widget needs to instantiate correctly.

We strongly recommend that you make use of our CDNs to make updating the DirectID Widget as straightforward as possible. Failure to use our CDNs may result in backward compatibility issues with older versions of JavaScript. You can find the paths for our Widget versions in our Release Notes section. 

Add a link to the DirectID CSS in the head of your HTML document:

    <link href="CSS-CDN" rel=”stylesheet”>


Add a link to the Direct ID JavaScript at the end of your HTML document:

    <script src=”JS-CDN”></script>


Implementing the Widget

Include an HTML tag (normally a <div> tag) with did as its id attribute value in the body of your HTML document. Moreover, your server side will dynamically author a data-token attribute of the same HTML tag and put a valid user session token as its value. For example, the following code shows a <div> tag that implements the DirectID Widget:

    <div id=”did” data-token=”User-Session-Token”></div>


You’ll notice that we have placed the user session token generated in the previous step as value of the data-token HTML attribute.

This is all that you need to do to get the DirectID Widget to operate within your page. You should now be able to test the Widget using either live bank or credit card accounts or by using test accounts provided by your account manager. It is better to use test accounts for initial testing, since your transactions with live accounts will not be masked unless requested by you.