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 or false

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.