Working with WSDL Files
Integrate with Vindicia Retain by making SOAP calls directly to Vindicia’s Web services.
Because of the prevalence of Web services with SOAP as a protocol of choice for integration of disparate systems, most programming languages have built-in support for developing SOAP client-server code. A third-party plug-in or library might also be available for your language of choice. For example, Python programmers can build SOAP client-server code with the SOAPy library. Programming a SOAP client in the language of your choice usually requires access to a Web Services Description Language (WSDL) file that describes the Web service for which you wish to create a client.
Vindicia Web services consist of a set of objects and the SOAP calls that they support (Vindicia Subscribe SOAP API), with the calls described in a set of WSDL files. These WSDL files support document-literal SOAP calls, as defined in the World Wide Web Consortium (W3C) standards. Each WSDL file corresponds to a logical object commonly used in billing solutions. Objects (complex types) shared across all WSDL files are defined in the Select.xsd file that every WSDL file includes in its definition.
Each WSDL file describes a set of calls supported by the logical object. For example, the Transaction.wsdl file describes the calls with which you can perform activities on a transaction (a Transaction object) in Vindicia Retain. Make an update call to create or update an Account object; or a fetchByMerchantTransactionId() call to retrieve a Transaction object by the unique ID assigned by you when you created the object.
Each WSDL file defines only one SOAP port bound to the object-specific interface (a set of methods). For example, Select.wsdl defines a port called SelectPort, which supports only the SOAP calls that relate to the Select object.
The ports defined in each of the WSDL files are associated with the same SOAP address (endpoint). That address is a script on Vindicia servers that receives all SOAP calls and routes them to object-specific code for further processing, depending on which objects the calls are for. For example:
<service name="Select"> <port binding="tns:SelectBinding" name="SelectPort"> <soap:address location="https://soap.vindicia.com/soap.pl" /> </port> </service>
Each WSDL file imports the Select.xsd schema file, which defines the data structure of all top-level and helper objects. Your client code must be able to access this schema file.
Specifying the SOAP Address
By default, the SOAP address points to Vindicia’s production servers. Before going live with Vindicia Retain, test your integration code in a Vindicia sandbox server. If your language-specific implementation of a SOAP client does not override the SOAP address specified by the WSDL file, you can download the WSDL files from Vindicia, save them locally, and update the SOAP address to reflect the sandbox and Vindicia Subscribe SOAP API version you will use.
For example, if you wish to call in to Vindicia Subscribe on Vindicia’s Prodtest sandbox, update the service attribute in your local WSDL file as follows:
<service name="Select"> <port binding="tns:SelectBinding" name="SelectPort"> <soap:address location="https://soap.prodtest.sj.vindicia.com/ soap.pl" /> </port> </service>
Setting up your SOAP Environment
Before developing client code with the Vindicia Retain WSDL files:
1. Download the WSDL files and the schema file from the Vindicia servers.
For Vindicia Subscribe API production releases, download from the following sites:
- WSDL file: https://soap.vindicia.com/version/object.wsdl, for example, https://soap.vindicia.com/1.0/Select.wsdl
- Schema file: https://soap.vindicia.com/version/Select.xsd
For Vindicia Subscribe API nonproduction releases that are in Vindicia’s staging servers for testing prerelease client regression, download from the following sites:
- WSDL file: https://soap.staging.sj.vindicia.com/version/object.wsdl
- Schema file: https://soap.staging.sj.vindicia.com/version/Select.xsd
2. Optional. Update the SOAP endpoint address to reflect the server to which to send your SOAP calls, assuming that you cannot programmatically do so in your client code.
3. Generate local stub or proxy objects with language-specific tools. For example:
- If you program in Java and are using the Apache Axis library to work with SOAP, generate local stub objects with the utility WSDL2Java.
- If you program in .Net with C#, import the WSDL files into your project to automatically generate local stub objects.
- If you program in another language, such as Python, for which no appropriate tools are available, consult the language- or package-specific SOAP documentation on how client code can make the SOAP calls as described in the WSDL files.
4. Ensure that your SOAP library supports making SOAP calls to external servers through HTTPS.
For security, Vindicia does not support HTTP-based SOAP calls. You might need to install additional SSL-specific libraries on your system.
Tips for Developing SOAP Clients
- In most SOAP libraries, you can set a timeout value for the SOAP calls that you make from the client to the server. Ensure that the value is globally configurable. You may wish to change the value to fine-tune it, depending on the amount of data you will be sending or receiving from the Vindicia servers.
- Every SOAP call you make to Vindicia Subscribe requires that you pass an Authentication object, which contains the SOAP login and password assigned to you by Vindicia. Make those credentials globally configurable. When you switch to production, you must log in with credentials that differ from those used in testing against Vindicia’s sandboxes.
- You might also want to make the Vindicia server, to which your client code points globally, configurable. This can simplify the process of switching from testing to production.
- Log all calls made with the Vindicia Subscribe client library. At a minimum, log the following:
- Classes and methods
- The Vindicia Return data structure (all three fields)
- SOAP envelopes that are sent to and received from Vindicia servers may be used to debug data-related errors. Most SOAP libraries allow you to add an option to log these envelopes.