Sessions
The first step to using API requests is to initiate a session with the IBM® Safer Payments server.
API access, whether by users or by third-party components, is granted only within a valid IBM Safer Payments session and must be associated with a user account. An exception to the rule is the API request ping. The JavaScript code in the browser cannot be fully protected against manipulation. Therefore, the actual session validity is kept within IBM Safer Payments where it cannot be manipulated. In addition, all API requests are subject to the user and group privilege model that is defined in IBM Safer Payments.
Many websites use an HTTP server to deliver HTML pages to the browser upon its requests. These HTML pages can be static or server generated. IBM Safer Payments uses a different approach, which is called a Single Page Application. When users access IBM Safer Payments from the API URL, the embedded HTTP service function of IBM Safer Payments delivers an HTML page to the browser that contains only links to JavaScript libraries. These libraries contain the entire user interface from the moment that the user interface starts running.
After the JavaScript libraries are loaded, which typically takes less than a second depending on the environment, the IBM Safer Payments Controller in the web browser is started. If it finds no valid session, the controller first invokes the login process. Then, depending on the user actions, the controller moderates the communication between the browser and IBM Safer Payments by using asynchronous requests. For third-party components that access the API, a session starts directly with the invocation of the login process.
The API identifies a session through a browser cookie. The response to a successful login request contains an HTTP cookie that is stored with the browser. For third-party component access, the cookie is set, for example, by the line:
Set-Cookie: sessionId<n>=<sessionId>;path=/; !HttpOnlyThe line is contained in the HTTP header of the IBM Safer Payments response.
The <n> variable corresponds to the instance ID of the respective IBM Safer Payments instance. It enables a user to have multiple sessions with different IBM Safer Payments instances open on the same browser.
Now every request from the browser or the third-party component must send the sessionId<n> as a cookie in its HTTP request header, for example, by including the following line in its header:
Cookie: sessionId<n>=<sessionId>The session ID value remains the same during the session.
If the setting for Cross-site request forgery protection is enabled in , IBM Safer Payments uses a second session token to prevent Cross-Site Request Forgery (CSRF) attacks. This token is returned as part of a successful login API response, along with other responses, as JSON variable csrfToken. Its value must be passed back with each subsequent request as the HTTP header element:
CsrfToken: <csrfToken> The sequence of JSON request objects and variables must exactly follow the sequence that is specified in the IBM Safer Payments API Reference Guide. Objects and variables can be omitted if the default value works. Extra objects and variables can be given but are ignored.
JSON examples in the documentation contain white spaces and line feeds for readability. The actual API responses might not have them for reasons of efficiency.
The response variable reloadUserProfile indicates whether an administration change impacted the current user session. If reloadUserProfile is true, update the user profile, if it is cached, from IBM Safer Payments to avoid errors from actions.
Timestamp values are numeric and denote seconds after 1970-01-01 00:00:00 (UTC). The IBM Safer Payments server is in UTC. Timestamps are converted to local time by the component that is using the API. The earliest timestamp value that can be expressed is -549755813887, and the latest is +549755813887. The value -549755813888 denotes a nil value, which means that the timestamp value is not set.