JSON Encoding Details

This page describes how values are encoded to JSON for use with the Paytronix API. All API calls are documented using JSON.

Encoding of Types

Boolean

JSON: Encoded as a JSON boolean.

Examples:

{ "field": true }

{ "field": false }

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" }

Date

JSON: A string that represents a date, formatted as yyyy-mm-dd.

Example:

{ "field": "2014-06-13" }

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-0400" }

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" }

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 }

Object

JSON: As a JSON object. The particular fields expected are detailed in the description.

Example:

"obj": {
    "field1": "foo",
    "field2": 1234,
    …
}

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": []

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": {}

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.