Knowledge Base Best Practices

TSYS' API Versioning

TSYS is constantly making advancements to its products and APIs. Being able to add new features to our products – like EMV or Loyalty – without breaking our APIs and our APIs’ consumers – our partners Points of Sale and online Shopping Carts – is one of our greatest strengths.

We’ve designed our APIs to be flexible and future-proofed so that we can continue to advance the state of payments.

We promise not to break our APIs by removing any data or by changing their behavior. To support new use cases, we will occasionally return new fields in our responses and will add new optional parameters to our requests. So we need your help. Below are a few tips to help your software be flexible when it comes to our API responses.

Don't use strictly validating XSD or WSDL parsers.

If your toolchain performs strict validation of XML documents, please disable that feature. Your version of our WSDL or XSD may be out of date with our master copy as our APIs have evolved in a non-breaking way. Strict validation will cause your Point of Sale to break, even though our APIs remain backwards-compatible.

As one example, the popular Java XML framework, JaxB, employs strict XML schema validation by default. See this article on Binding WSDL to Java with JAXB for details on how to employ less-strict validation.

Use off the shelf XML, SOAP, and JSON parsers & generators.

Don’t try to construct or parse XML, SOAP, or JSON documents by hand. Instead, use free, off the shelf tools. Hand-written tools tend to be fragile, and often don’t handle features like XML escaping properly.

Respect our APIs' schemas

Often, additive enhancements are released to our APIs that will result in new information appearing in a response. It is important to be able to gather the information you are looking for from a response message without using strict logic that would break down in the event a new field appears.

Things to avoid: 
  • Using field ordinals to locate specific response info (eg: looking for information in the 4th field in the transaction response message)
  • Hard coding against the entierty of the response structure in a manner that would throw an exception in the event of new fields.
Here is an example using a dummy response message: 

Going from this: 


To this: 



should not result in a fatal error from the POS.