JSON and XML Encoding Details¶
This page describes how values are encoded to JSON for use with the Paytornix API. All API calls are documented using JSON however XML can also be used by changing the endpoint URL from .json
to .xml
and providing appropriately formatted XML.
Encoding of Types¶
- Boolean
JSON: Encoded as a JSON boolean.
Examples:
{ "field": true }
{ "field": false }
XML: Encoded as the text
true
orfalse
Examples:
<field>true</field>
<field>false</field>
- String
JSON: A string which may have particular formatting requirements detailed in the description of the field, such as an enumeration of accepted values.
Example:
{ "field": "foo bar" }
XML: A text fragment which may have particular formatting requirements detailed in the description of the field, such as an enumeration of accepted values.
Example:
<field>foo bar</field>
- Date
JSON: A string that represents a date, formatted as
yyyy-mm-dd
.Example:
{ "field": "2014-06-13" }
XML: A text fragment that represents a date, formatted as
yyyy-mm-dd
.<field>2014-06-13</field>
- DateTime
JSON: A string that represents a date and time, preferably formatted using ISO8601 format. Also can be formatted
yyyy-mm-dd hh:mm:ss [+-zzzz]
Example:
{ "field": "2014-06-13T23:01:50.481-0400" }
XML: A text fragment that represents a date and time, preferably formatted using ISO8601 format. Also can be formatted
yyyy-mm-dd hh:mm:ss [+-zzzz]
Example:
<field>2014-06-13T23:01:50.481-0400</field>
- Decimal
JSON: A string that represents a decimal number, formatted as
[+-]mmmm[.nn]
: an optional sign indicator followed by sequence of digits and then optional decimal point and fractional part. Represented as a string instead of JSON native number due to some libraries using an imprecise floating-point type to represent this value, which would be inappropriate for currency values.Examples:
{ "field": "145.92" }
{ "field": "-45" }
XML: A text fragment that represents a decimal number, formatted as
[+-]mmmm[.nn]
: an optional sign indicator followed by sequence of digits and then optional decimal point and fractional part.Examples:
<field>145.92</field>
<field>-45</field>
- Integer or Long
JSON: A 32-bit (Integer) or 64-bit (Long) integral value, in normal JSON format, e.g.
1234
or-810
Example:
{ "field": 145 } { "field": -45 }
XML: A text fragment representing a 32-bit (Integer) or 64-bit (Long) integral quantity formatted in the usual way, e.g.
1234
or-810
Example:
<field>145</field> <field>-45</field>
- Object
JSON: As a JSON object. The particular fields expected are detailed in the description.
Example:
"obj": { "field1": "foo", "field2": 1234, … }
XML: As an element with a subelement for each expected field, detailed in the description.
Example:
<obj> <field1>foo</field1> <field2>1234</field2> … </obj>
- List[…]
JSON: As a JSON list with each element encoded according to the contained type.
List[Int] example:
"lstInt": [ "foo", "bar", … ]
List[Object] example:
"lstObj": [ { "a": 1, "b": true }, { "a": 2, "b": false }, … ]
Empty list example:
"lstObj": []
XML: As a
<array>
element with<item>
subelements, each<item>
element containing one value encoded according to the contained type.List[Int] example:
<lstInt><array> <item>foo</item> <item>bar</item> … </array></lstInt>
List[Object] example:
<lstObj><array> <item><a>1</a><b>true</b></item> <item><a>2</a><b>false</b></item> … </array></lstObj>
Empty list example:
<lstObj><array /></lstObj>
- Map[…]
JSON: As a JSON object with each field value encoded according to the contained type.
Map[Int] example:
"mapInt": { "foo": 1, "bar": 2, … }
Map[Object] example:
"mapObj": { "foo": { "a": 1, "b": true }, "bar": { "a": 2, "b": false }, … }
Empty map example:
"mapObj": {}
XML: As an element for each key with the contents of the element encoded according to the contained type.
Note
Empty maps are represented specially in XML using the special element
<empty />
. See example below.Map[Int] example:
<mapInt> <foo>1</foo> <bar>2</bar> … </mapInt>
Map[Object] example:
<mapObj> <foo><a>1</a><b>true</b></foo> <bar><a>2</a><b>false</b></bar> … </mapObj>
Empty map example:
<mapObj><empty /></mapObj>
Optional and Required Fields¶
Fields marked (required) in the documentation of a request endpoint must be given when submitting requests, and fields marked (required) in the documentation of a reply will always be given by the Paytronix system.
Similarly, fields marked (optional) may be omitted entirely from the request and may or may not be provided by the Paytronix system in replies. For replies, the description of a field will often explain when the field will be given. Note that in JSON an optional field may be given with the value null
rather than omitted entirely, but this should be avoided if possible.