Using the WebSDK
This topic provides detailed information on how to use the WebSDK.
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:
- Initialize
jwk_set
from your server. - Initialize
user_session_initialization_data
from your server.
Note: If you are using the V2 version, useconst init = await
. - Create a user session by sending
init.deviceData
to your server. - 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.
Updated 12 months ago