> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSession Object

The `WebSession` object must be created before serving the order form to the customer for submission to the Vindicia server.

The `WebSession` object:

* Tracks the submission of an order form containing sensitive payment data. Use the `WebSession`'s `VID` as a session ID, to track the session from your customer's first order form request, to your final success or failure page for the session.

* Establishes a time limit for the entire sequence.

* Ensures that a single form submission from a customer results in only one API call, specified when the session is initiated (see the `WebSession` object's `method` data member). That way, if the customer submits the same form repeatedly, HOA does not make multiple API calls, resulting in the creation of multiple Subscribe objects. The `WebSession` object supports the following Subscribe API calls (methods):
  * `Account_Update`
  * `Account_UpdatePaymentMethod`
  * `AutoBill_Update`
  * `PaymentMethod_Update`
  * `PaymentMethod_Validate`
  * `Transaction_Auth`
  * `Transaction_AuthCapture`

* Stores the result of the Subscribe API calls made by HOA after finalization of the `WebSession` object. Your success / failure page then examines this information to determine its content, and directs the customer to the appropriate next steps. (See the `WebSession` object's `apiReturn` attribute in Section 19.1: WebSession Data Members in the **Subscribe API Guide.)**

* Holds some of the data required to complete the Subscribe API call that HOA makes after the customer has submitted the form. (See the `WebSession` object's `privateFormValues` attribute in Section 19.1: WebSession Data Members in the Subscribe API Guide.)

  For details on the `WebSession` object's attributes, see Section 19.1: WebSession Data Members in the **Subscribe API Guide.**

  The following example shows a typical initialization of a `WebSession` object. This example creates an `AutoBill` object for a new subscription, without passing sensitive Payment Method information through your servers. When a customer requests a page to start a subscription, initiate a `WebSession` object.

To populate the data in the `WebSession` object:

* HOA calls `AutoBill.update` when you finalize the `WebSession` object.

* `AutoBill.update()` may use an existing `Account` object for the customer.

  **Note:** Do not allow this object's VID to appear in the form sent to the customer's browser, not even as a hidden element.

* `AutoBill.update()` uses an existing `Product` object.

  **Note:** Do not allow this object's VID to appear in the form sent to the customer's browser. Hiding this VID prevents hackers from specifying a random Product ID, that may correspond to a Product ID that you do not wish to make available for subscriptions in this context.

* `AutoBill.update()` uses one of two existing `BillingPlan` objects. (Specify existing Billing Plan IDs to prevent other, possibly inactive or invalid, IDs from being submitted. This helps to regulate and control the AutoBill creation process.)

Because all POSTed data is submitted through an HTTP Post, it must be submitted as name-value pairs.

**Note:** These are HTTP name-value pairs; not Subscribe `NameValuePair` objects.)

```

 $ws = new WebSession();
  
 // HOA must use Subscribe API version 3.4 or later to make the 
 // AutoBill.update call
 $ws->setVersion('3.4');
  
 // HOA should make an AutoBill.update call when the form
 // is submitted
  
 $ws->setMethod('AutoBill_Update');
  
 // Capture the customer's IP address. When the customer submits the form,
 // it should come from the same IP address
  
 $ws->setIpAddress("124.23.210.175");
  
 // Page to which HOA will redirect customer's browser after 
 // successfully storing the data received when the customer 
 // submits the form
  
 $ws->setReturnURL("https://merchant.com/subscribe/success.php");
  
 // Page to which HOA will redirect customer's browser if HOA fails to 
 // store the data received when the customer submits the form
  
 $ws->setErrorURL("https://merchant.com/subscribe/failed.php");
  
 // Private name-value pairs. These are needed to create the AutoBill 
 // object, but are NOT included in the customer form 
  
 $pnv1 = new NameValuePair();
  
 // The name is a flattened object name, concatenated
 // with attribute names with an underscore. 
  
 // The Subscribe Account object for which HOA should create the
 // AutoBill object
  
 $pnv1->setName('vin_Account_merchantAccountId');
 $pnv1->setValue('df943'); 
  
 // The Subscribe Product object HOA should use to construct
 // the AutoBill object
  
 $pnv2 = new NameValuePair();
 $pnv2->setName('vin_Product_merchantProductId');
 $pnv2->setValue('BlorgWars II'); 
  
 $pnv3 = new NameValuePair();
 $pnv3->setName('vin_BillingPlan_merchantBillingPlanId');
  
 // When customer submits the form, the Billing Plan
 // must be one of these two comma separated values
  
 $pnv3->setValue('GoldAccess2010, PlatinumAccess2010'); 
  
 $ws->setPrivateFormValues(array($pnv1, $pnv2, $pnv3));
  
 // Create method parameter name-value pairs. These are needed to make the 
 // AutoBill.update call which takes parameters in addition to the 
 // AutoBill object itself. Do not allow these to come from the form 
 // submission, because that makes them susceptible to hacking
  
 $mpnv1 = new NameValuePair();
  
 // The name is flattened object name, method name, and 
 // parameter name, concatenated with underscores. 
  
 $mpnv1->setName('AutoBill_Update_minChargebackProbability');
 $mpnv1->setValue('80'); 
  
 // Leave other parameter values to their default values
  
 $ws->setMethodParamValues (array($mpnv1));
  
 // Now create the WebSession object on Vindicia servers
 // by making the SOAP call to initialize the object
  
 $response = $ws->initialize();
  
 if ($response['returnCode'] == 200) {
  
 $ret_ws = $response['data']->session;
  
 // The VID of the WebSession object serves as session id
  
 $sessionId = $ret_ws->getVID();
  
 // Embed the sessionId as a hidden field named 
 // vin_WebSession_VID in the order web form
  
 // Compose and present the order web form to the customer here
 }
 else {
 // Return error to the customer who requested the web order form
 }
```

Note that this example stores the merchant IDs of the `Account`, `BillingPlan`, and other objects as private values in the `WebSession` object, and assumes that objects with these IDs already exist in Subscribe. (Note that use of the forward slash character (/) in merchant identifiers is not allowed. See [Merchant Identifiers](Merchant_Identifiers#) for more information.) Always specify merchant IDs of objects as private values stored in the `WebSession` object, even if the objects do not yet exist. These are your internal object IDs; for security reasons do not pass them in through the form submission, or store them as hidden fields in the form. If an object ID is present in the `WebSession` object's private values, when HOA completes the desired API call, HOA first looks for an object with that ID in the Subscribe database. If no such object is available, HOA creates a new object with that ID, and populates it with related data, either submitted through the form, or previously stored in the `WebSession` object.

For example, if an `Account` with `merchantAccountId: df943` does not yet exist in Subscribe, when the `WebSession` is finalized, HOA will create a new `Account` object with `merchantAccountId: df943`. In this case, the `Account` attributes, such as customer's name, email, and shipping address, must be passed in through the form; which means that your form must include the fields necessary for your customer to submit this information.

The `WebSession` object created remains valid for one hour (by default), within which time the customer must complete and submit the form.

**Parent topic:**[Working with HOA with Hosted Fields](../topics/Working_with_HOA_with_Ho)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.