The API is a standard “rest-like” interface available over the internet. Most of the transactions are an HTTP POST with the body of the request containing JSON as described below. A few calls are for query purposes only and the interaction takes the form of an HTTP GET. The body of the response is also JSON as described below.
In most the request/response pairs there are timing elements. Both are UTC timestamps (based in GMT). The request date/time records the time just as the request is formed to be sent and the response date/time records when the response was formed to be returned after the request has been processed. If the request time is not specified, the system will record the time the request was received. These time stamps have a granularity in seconds. The format of these elements is: YYYY-MM-DD hh:mm:ss using Y for year, M for month, D for day, h for hour, m for minute, s for second example: 2012 09 20 14:32:46.
HTTP Settings
Calls are standard HTTP POSTS. The listen port for requests is 8080.
HTTP Header Fields used:
- Content-Type should be set to:
application/json - Accepts should be set to:
application/json - Authorization: A timed bearer token authentication system is being used to secure access to the API. See the section below for more information.
Synchronous vs. Asynchronous mode
Responses from the API can function in either a blocked (synchronous) or unblocked (asynchronous) request/response mode. Most partners have requested the synchronous model so this is the default mode. The response mode can be chosen on each individual call. Within the request payload is an element called “asynchResponse”. The expected value of this element is a URL where the caller will receive the processed response in the same payload format as the synchronous response. If this value is present and looks to be a valid URL, then the asynchronous response mode is activated.
In the asynchronous response mode, a response will come back immediately that will indicate that the request has been received and validated. If the request does not validate correctly, the immediate response will indicate an error and there will not be a forthcoming asynchronous response. If the immediate response does not indicate an error, Pyxis will process the request and then, using WebSockets, send the processed response to the URL indicated in the “asynchResponse” request element. Again, the payload of the async response will be the same as the returned payload for a synchronous request.
There are a few Pyxis APIs that will do not have asynchronous response mode available, these are, usually, straight query requests that do not interact with a gateway. For the majority of the APIs that can response asynchronously, you will probably need a way to tie requests and responses together. Each request payload has an optional “externalTransactionId”. This element is for transaction IDs that originate in the caller’s system and is, if present, simply echoed back in the response so this can be used to know which response goes with which request. The contents of this element are up to the caller; to Pyxis, it is a 64-character string.