CashBox API Overview

Each CashBox object consists of data members and methods that operate on those members. The data members fall into one of the following categories:

Standard, built-in data types, such as integers or strings, that are common to programming languages.

Enumerations, which are scalar types coded as standard data types, but which are restricted to a specific set of legal values.

Data structures, which consist of multiple data members, each of which can be of different data types.

Arrays, containing zero or more data elements, all of which must be the same data type.

A CashBox object’s methods are functions that require one or more input arguments. Methods always return a code that indicates the success or failure of the function call. In the event of failure, the code value should provide clues to why the call failed.

The CashBox API is a structured language, and requires input parameters to be entered in the order shown. Parameters must be place-marked if not specified.

This guide presents Objects and their data members and methods alphabetically, for ease of reference. Variable parameters for the methods are presented in syntactical order.

Input Parameters

The CashBox SOAP API requires input parameters to be entered in the order shown, and must be place-marked if not specified.

For example, if you wish to use the Account.makePayment method to enter a payment against an Account, and you wish to add a note without specifying the invoiceId or overageDisposition, you must enter null for those two parameters.

(See the Account.makePayment method for details.)

To enter a payment of $37 against an Account, call

 

Account->makePayment($acct,

$paymentMethod, 37, USD, null, null, "note")

Calling

 

Account->makePayment($acct, $paymentMethod, 37, USD, "note")

would result in a payment applied to invoiceId "note," with no note included, which is, most likely, an invalid call.

The Return Object

All methods in the CashBox API return a Return object, which contains the return codes for the call.

The Return object contains three data members:

returnCode: This data member contains a value that corresponds to a standard HTTP return code. For values of 400 or higher, assume that your call failed. The failure could be due to several reasons, such as an authentication failure or a CashBox failure to find any objects that match your input. See Table 1: Standard Return Codes for a list of the most common return codes.

returnString: If returnCode indicates an error condition (a non-200 return code), your application can check returnString for further information. Use the CashBox API to generate a log of returnString, to help you debug your application in the development and production phases.

soapId: This ID is returned for certain calls to Vindicia, especially those made to submit a batch of data (for example, a batch of transactions or account activities) for ChargeGuard processing. This ID helps Vindicia track your batched data in Vindicia’s system and, if the ID is available, you should log it in your application. If an incident arises that requires troubleshooting by Vindicia, a Vindicia representative might ask you for this ID to determine the status of your data.

Some return strings contain information specific to the call for which the return was generated. In some cases, these will take the format:

 

Unable to load product by VID input-VID: No match.

where input-VID specifies the object or call to which the return error applies.

In some cases, these will take the format:

 

Unable to load product by VID input-VID: error-description.

where error-description more specifically explains the cause of the error. In both cases, variable text is displayed in bold-italic.

The following table lists and describes the most common return codes. If a method returns different return codes, they are listed with the method.

Table 1  Standard Return Codes

Return Code

Description

200

The call succeeded.

400

Your call failed, which could be due to an authentication failure, invalid user input, or a CashBox failure to find any objects that match your input.

403

The Vindicia server cannot authenticate your request.

500

The Vindicia server encountered an internal error. That error could occur for various reasons, the most common being an incorrectly populated input object, especially when you are making the call from a client library whose language does not support strict data-type checking. For resolution, especially during the development phase, contact Vindicia Technical Support.

503

A Vindicia back-end service, such as a database, is unavailable. Retry your call later.