SOAP API Guide
The API guide describes each available resource in the CashBox API. Learn about parameters, errors, and how to format your requests.
CashBox is an on-demand solution for one-time and recurring billing, available for integration with your application through an object-oriented application programming interface (API), based on the Simple Object Application Protocol (SOAP). The CashBox solution is accessed through a public API to the CashBox application, which is hosted and maintained on the Vindicia network.
The CashBox API leverages a Service Oriented Architecture (SOA). This means that CashBox users are not required to install application software on their network, but instead use SOAP to communicate with the CashBox application. They do this either through a thin client provided by Vindicia, or through a WSDL published by the Vindicia SOAP servers (http://soap.vindicia.com/ 1.0/Transaction.wsdl). These SOAP servers comprise the first tier of the Vindicia network—the only tier that is publicly accessible.
This CashBox API Guide describes the Objects available in the CashBox solution, and provides pseudo-code examples.
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.
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 makePayment method for details.)
To enter a payment of $37 against an Account, call
Account->makePayment($acct, $paymentMethod, 37, USD, null, null, "note")
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 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. To help you debug your application in the development and production phases, use the CashBox API to generate a log of returnString.
- 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 enables Vindicia to track your batched data in the Vindicia 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.
The call succeeded.
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.
The Vindicia server cannot authenticate your request.
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.
A Vindicia back-end service, such as a database, is unavailable. Retry your call later.