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 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

Home

Guides

APIs