Skip to main content
Vindicia Knowledge Center

WebSession Data Members

WebSession Data Members

WebSession Data Members

The following table lists and describes the data members of the WebSession object.

 

Data Members

Data Type

Description

apiReturn

Return

Read-only. The Return object returned to HOA by the API call specified in the method attribute. This attribute is available only after the WebSession object is finalized.

errorURL

string

Optional. The URL of your site’s dynamic page, to which HOA redirects the customer’s browser at form submission if initial validation (e.g. credit card Luhn check, expiration date does not begin with 20 ) of the form contents fails. If the HOA form post was made using Ajax, and there was a similar error, this value is returned in a Redirect-URL header instead of the redirect.

In either case, HOA includes the VID of the WebSession object when redirecting or returning the headers. On this page, fetch theWebSession object with that VID as the search criterion, and extract the reason why HOA’s call failed, available through the returnString and returnCode attributes. Use this string to create a failure message to send to the customer in HTML.

If you do not specify this attribute, HOA uses the returnURL value.

expireTime

dateTime

Read-only. The time stamp of when this WebSession object expires. WebSession objects are valid (by default) for one hour. If the customer submits the order form after that time, HOA redirects the customer’s browser to the page specified by errorURL.

When you fetch a WebSession object, if the current time is past this time stamp and the returnCode and returnString attributes are not populated in the WebSession object, assume that the customer never submitted the form, and that the WebSession object is no longer valid.

ipAddress

string

Required. The IP address from which the customer requested the order form. When the customer submits the form, HOA checks if the submission originated from the same IP address. If not, HOA does not make the API call specified in the method attribute. Instead, it updates the WebSession object with the error return code 401, and the return string “IP address does not match value associated with WebSession,” and redirects the customer’s browser to the page specified by errorURL.

method

string

Required. The CashBox API call made by HOA at form submission. The data loaded in the privateFormValues data member of this WebSession object and the data submitted through the form should be relevant to this call.

CashBox supports the AutoBill.update, Transaction.auth, Transaction.authCapture, and PaymentMethod.update calls. To specify a call in this string, concatenate the object name with the method name separated by an underscore, and omit the parentheses, for example, Transaction_authCapture.

methodParamValues

NameValuePair[]

Optional. The values for some of the parameters required by HOA to make the API call specified in the method attribute. To avoid hacking, include them here to exclude them at form submission.

For example, if the call is AutoBill.update, exclude the tolerance threshold in the risk score (minChargebackProbability) at form submission. The name for the value is the flattened object name, method name, and parameter name, concatenated with an underscore, for example, AutoBill_Update_minChargebackProbability.

See The NameValuePair Object.

nameValues

NameValuePair[]

Optional. The name–value pairs to include in the objects created by HOA through the API call specified in the method attribute. Include this attribute when initializing the WebSession object. For example, if that call creates an AutoBill object and you want the latter’s transactions to be routed to your payment processor under a specific division ID, include that ID in this name–value pair with the name vin:Division.

See The NameValuePair Object.

postValues

NameValuePair[]

Read-only. The name-value pairs stored by HOA in the corresponding WebSession object at form submission by the customer if you include non-Vindicia form elements, those with no vin prefix in their names, in the order form. On your success or failure page, extract these pairs from the WebSession object you fetch.

See The NameValuePair Object.

privateFormValues

NameValuePair[]

Optional. The object attribute values required by HOA to complete the API call specified in the method attribute at form submission. Once this attribute is populated, your application need not pass the related data to the form, which secures it against hacking.

For example, if the call is AutoBill.update, specify the customer account to which the call applies by populating this attribute with the Account object’s VID. That way, hackers cannot change that VID in the form, because HOA looks it up only in this data member, privateFormValues, instead of from the data in the form.

Also, if a Vindicia form element can have only one of several values, include all the values in privateFormValues. That way, HOA can verify the validity of the form element’s value at form submission. For example, when creating an AutoBill object, to enable the customer to choose only one of two billing plans, include the IDs of the two billing plans in this attribute. Afterwards, embed two radio buttons in the form with the same values.

The names of the form elements should match the names in this attribute. The names for these pairs follow the same convention as that for order-form elements; see Hosted Order Automation in the CashBox Programming Guide

Note Commas are a special reserved character for use in this data member, and should be used only as a separator between multiple possible values for the name of a name-value pair.

For example, to create an HOA order form which allows your customer to choose between three Billing Plans with billingPlanId gold, silver, and platinum, use the privateFormValues to populate the following name-value pair when initiating the WebSession object:

vin_BillingPlan_merchantBillingPlanId =

gold,silver,platinum

Then, in the web order form presented to the customer, include a multiple choice field with namevin_BillingPlan_merchantBillingPlanId. This field will allow your customer to choose one value from the three offered: gold, silver, and platinum.

Do not use commas as values in the privateFormValues for any other purpose.

See The NameValuePair Object.

returnURL

string

Required. The complete URL of your site’s dynamic page, to which HOA redirects the customer’s browser at form submission, after HOA has successfully made the API call specified in the method attribute. If the HOA form post was made using Ajax, this value is returned in a Redirect-URL header instead of the redirect.

While redirecting the customer’s browser to this page, or passing the header, HOA includes the VID of the WebSession object. In your code to construct this page, fetch the WebSession object with its VID as the search criterion, and the CashBox object created by the API call specified in the method attribute. Afterwards, extract the information from the fetched objects and create a success message in HTML to send to the customer.

version

string

The CashBox API version HOA should use for the call specified in the method attribute. This value must be 3.3 or higher.

VID

string

Vindicia's Globally Unique Identifier (GUID) for this object. When creating a new WebSession object, leave this field blank; it will be automatically populated by CashBox.

We suggest that you embed the VID as a hidden form element named vin_WebSession_vid in the order form you present to the customer. That way, when the customer submits the form, HOA can load the corresponding WebSession object.

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top