A session can be thought of as a user or device level session, identifying and validating the user and/or device for whom an endpoint is being exercised. It is distinguished from a partner-level session, described in Partner Authentication, used to establish a partner’s daily general access to the API:

  • A partner-level session is a prerequisite to and enables access to the rest of endpoints in the API. It is established essentially once per day to enable general partner level communications with the Netspend API. See Partner Authentication for more details about this sort of session.

  • A session refers to the as-needed establishment of additional confirmation of the device plus maybe the account or person needed for a request. To be clear, a session is presumed to be intrinsically tied to a device being used by a person.

There are a few types of sessions that can be created:

Session TypeDescription
AnonymousUsed typically to validate at the device level when onboarding a new account or person to help pre-assess any risks at that level.
AccountUsed for endpoints requiring validation of an account along with the device being used by the account holder when making requests.
PersonUsed for endpoints requiring validation of a person along with the device being used by the person when making requests.

In general, though, if the account or person is known, it is best to establish a session for that account or person when making any requests on their behalf.

The Netspend SDK

At base, sessions cannot be established without secure communication of information about the device, account, or person the session is for. To facilitate this, Netspend provides an SDK—the Netspend SDK, which can be embedded in your mobile application to perform encryption and decryption of sensitive data, including what is needed to establish sessions.

On the Netspend API side, there are a number of endpoints that send and/or receive encrypted data with the expectation of the Netspend SDK performing counterpart encryption and decryption on the partner application side. In general, to protect the privacy of customers and their Personally Identifiable Information (PII), the Netspend API only accepts PII like DOB and SSN in encrypted form.

Creating the Session

  • Establish partner session
  • Get session initialization information
  • Request session
    • See POST /sessions
      • Specify type of session
      • Specify expiration strategy
      • Include encrypted device and other data
      • Yields a session token
  • Use the session token for subsequent endpoint calls
    • The token yielded from the session request is then used as the value for the ns-session-id header when making calls to other Netspend API endpoints

Sample Flows

Establishing a Person Session on Login

The diagram below shows a typical interchange, when establishing a “person” session, between your mobile application, the Netspend SDK embedded in your mobile application, your back end systems, and the Netspend API.

Onboarding a New Account and Person

This diagram shows a potential flow where the session is gradually promoted from anonymous-to-account-to-person as the end user progresses through an account creation process. For more details on how to onboard a customer , see Customer Onboarding.

Person Session Usage in P2P Transfer

This diagram captures a potential P2P transfer flow, the endpoints for which depend on a person session being established in order to designate whether it was the sender or the receiver who made the request for the P2P transfer.

Session Enables Reading and Writing of Secure Data

When an account holder receives or sends secure data to or from the Netspend API, the data can be encrypted or decrypted by methods in the Netspend SDK, resident in the partner’s application, using the device JWK set information associated with the session.

The diagram below shows a flow where,

  • KYC identity questions are decrypted and displayed
  • Answers to the KYC identity questions are encrypted and submitted

Note: Any encrypted data the device receives from the server may not be persisted onto the device.