Skip to main content
Vindicia Knowledge Center




The finalize method instructs Vindicia’s Hosted Order Automation solution (HOA) to make the API call you specified in the WebSession object’s method attribute to create CashBox objects containing sensitive payment data. Before you make this call, HOA has all the necessary data to create the CashBox objects available to it through the attributes of the WebSession object you populated when you initialized it, and the data the customer submits on the order form. When you call finalize, simply pass in the ID of the sparse WebSession object (the VID). Do not populate any privateFormValues or post values. In rare cases, you can pass in MethodParamValues—for example if you want to pass in a campaign code to an AutoBill.update call after collecting it in the payment form.

Call this method when you receive a success notification from CashBox from the form post within HOA. This will either come as a 302 redirect to the returnURL you provided, or in the case of a form post using Ajax, it will be the returnURL string in the Redirect-URL field of the response header. When the customer submits the form, HOA receives the form data and stores it before redirecting the customer’s browser to the success page or passing the return header. The VID of the WebSession object embedded in the form identifies the context in which the customer submitted the form. It is available to you in your Success page as a parameter to the redirected URL. Thus, in your Success page code, you know which WebSession object instance you should finalize.

You can pass any CashBox API object attributes with this call that you did not originally pass in the initialize call. For example, if you did not collect the campaign code from the customer in the original purchase page where you made the WebSession.initialize call, you can collect it with the payment details, and pass it in with the WebSession.finalize call.

When you call WebSession.finalize, HOA not only makes the API call specified in the WebSession object’s method attribute, but also updates the WebSession object with results of the API call it made. These results are available to you in the updated WebSession object that is included in the response of this call (check the returnCode and returnString attributes of the WebSession object). Examine the results to determine the content of the customer’s browser page that awaits the response to the form submission.


srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

session: the WebSession object to finalize. Include the VID of the object here. HOA passes this VID in as a URL parameter when it redirects the customer’s browser to your success page from which you made this call.


return: an object of type Return that indicates the success or failure of the call.

session: the WebSession object updated with results of the CashBox API call specified in the method attribute, which HOA makes as a result of this call to create CashBox objects containing sensitive payment data.


In addition to those listed in Standard Return Codes, this call returns:

Return Code

Return String


One of the following:

  • Unable to load session: error-description.
  • Must specify a WebSession to finalize!


$sessionId = …; //passed in by redirected page

$ws = new WebSession($soapLogin, $soapPwd);

// finalize the WebSession so HOA can make the API call to
// create CashBox object/s containing sensitive payment
// information

$response = $ws->finalize();

if ($response['returnCode'] == 200) {

$updatedWs = $response['data']->session;

// Check if the API call HOA made to create the
// CashBox object containing sensitive payment
// data succeeded

if ($updatedWs->apiReturn->returnCode == 200) {


// Extract non-Vindicia values submitted by the web
// order form and process them to prepare the HTML to
// be returned to the customer

$postVals = $updatedWs->getPostValues()

// Assuming HOA created an AutoBill object, let's fetch it

$soapAbill = new AutoBill($soapLogin, $soapPwd);
$resp = $soapAbill->fetchByWebSessionVid($sessionId);

if ($resp['returnCode'] == 200) {

$createdAutoBill = $resp['data']->autobill;

// Get AutoBill contents here to be included in
// HTML returned to the customer.


else {

// The API call HOA made to create or manipulate object
// containing sensitive payment data did not succeed.
// Return error message to customer

$errorString =




else {

// Finalization failed
// Return error message to the customer


For Users

Learn More
For Users

Vindicia Subscribe Features

Learn More
Vindicia Subscribe Features
Back to Top