Installation

The WebSDK is a JavaScript implementation of the Netspend SDK for web based apps.

To use the WebSDK, you first need to add a script element to your webpage, which differs based on the environment you are targeting.

CERT Environment:

<script src="https://api-netspend-01.cert.aus.netspend.net/micro-apps/v2/sdk.js"></script>

PROD Environment:

<script src="https://api.netspend.com/micro-apps/v2/sdk.js"></script>

You can choose to change the script loader to execute asynchronously for initial load performance:

<script 
    src="https://api.netspend.com/micro-apps/v2/sdk.js" 
    async 
    onLoad="onNetspendSDKLoaded()"
    onError="onNetspendSDKLoadError(err)"></script> 

Initialization

To initialize the SDK, perform these steps:

1. Initialize jwk_set from your server.
2. Initialize user_session_initialization_data from your server.
   Note: If you are using the V2 version, use const init = await.
3. Create a user session by sending init.deviceData to your server.
4. To finish, pass encrypted_data from `POST /sessions to init.open().

The session is now open.

The below code sample illustrates implementation of the above steps.

try {
    // `jwk_set` from your server
    const init = await NetspendSDK.session.initialize(jwk_set);

    // `user_session_initialization_data` from your server 
    // in case you are using v2 SDK version
    // const init = await 
       NetspendSDK.session.initialize(userSessionInitializationData);

    NetspendSDK.session.state // 'initializing'

    // Send `init.deviceData` to your server to create a User session. 
    // Then, from the response of creating the User session on the server,
    // const payload = JSON.stringify({encrypted_data: init.deviceData});
    // const response = await fetch('/sessions', { body: payload });
    // const sessionData = await response.json();

    // pass the "encrypted_data" from POST /sessions to init.open() to finish 
    // opening the session

    // If you are using v2 version then payload will be created like below
    // const payload = JSON.stringify({device_data: init.deviceData});

    await init.open(sessionData.encrypted_data);

    NetspendSDK.session.state // 'ready'
    NetspendSDK.session.sessionId // Session ID, e.g.        
                                  // '3b10acea-e862-4720-91e0-fdd80a13eb28'
    // Now you can use the “encrypt()” and “decrypt()” methods
} catch(error){
    //Failure! See Error Handling Section
}

Note: If you are using the V2 version, the following payload is created:

const payload = JSON.stringify({device_data: init.deviceData});

Sessions Persist

📘

Sessions persist until you close them (see Ending a Session). Once a session is established, it remains accessible even if the browser is refreshed or closed, and can be retrieved upon the subsequent loading of the page.

As shown in the following code snippet, use state and sessionId to determine which session is currently active:

if (NetspendSDK.session.state === 'ready') {
    const myExpectedSessionId = getMyCurrentSessionId() // Determine the expected  
    session id using storage or your API
    if (NetspendSDK.session.sessionId === myExpectedSessionId) {
        // The session is good.

    } else {

        await NetspendSDK.session.close();
        // Initialize a new session using the steps above
    }
}

Ending a Session

Use the close() method to end the session as shown in the following sample code. The close() method performs necessary cleanup and then closes the micro app.

await NetspendSDK.session.close();
NetspendSDK.session.state // "uninitialized"
const container = document.querySelector('#netspend');
await NetspendSDK.microApp.initialize({
    //HTMLElement
    container,
    // The SDK ID you use for your integration is given from Netspend and is not a secret value.
    sdkId: 'NS-CERT-ABCDEF',
    // The theme configuration object
    theme: object,
    // Branding configuration object
    branding: object
});

Encrypting

Use the encrypt() method to encrypt the data as shown in the following sample code.

try {
    const encryptedData = await NetspendSDK.session.encrypt({
        some: "object",
        that_matches: "api documentation"
    });
} catch (error) {
    // Failure! See Error Section
}

Refer to the Netspend API Reference for encrypted_data in Requests.

Decrypting

Use the decrypt() method to decrypt the encrypted data as shown in the following code.

try {
    const decryptedDictionary = await
    NetspendSDK.session.decrypt(encryptedData);
    const value =
    decryptedDictionary.some_key_from_netspend_api_documentation ;
} catch (error) {
    // Failure! See Error Section
}

Refer to the Netspend API Reference for encrypted_data in Responses.

Web SDK and Micro Apps

Web SDK can be used by your front-end application that lets end-users access micro apps. Micro apps are optional user interfaces (UIs) that you embed into your products. In Netspend’s WebSDK, micro apps are loaded using an iFrame.

To use Netspend’s micro apps, first initialize the container.

Only one micro app is allowed at a time and WebSDK purposefully models the API as a singleton.

To no longer show the micro app, call NetspendSDK.microApp.close() from your app. Since this is an iframe in your app, you have the option of animating the transition on the parent element prior to calling NetspendSDK.microApp.close().

await NetspendSDK.microApp.close()

See Customization for detailed information on theme and branding.