.. _rest_encoding: 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: .. code:: javascript { "field": true } .. code:: javascript { "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: .. code:: javascript { "field": "foo bar" } *Date* **JSON:** A string that represents a date, formatted as ``yyyy-mm-dd``. Example: .. code:: javascript { "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]`` .. probably need more description Example: .. code:: javascript { "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: .. code:: javascript { "field": "145.92" } .. code:: javascript { "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: .. code:: javascript { "field": 145 } { "field": -45 } *Object* **JSON:** As a JSON object. The particular fields expected are detailed in the description. Example: .. code:: javascript "obj": { "field1": "foo", "field2": 1234, … } *List[…]* **JSON:** As a JSON list with each element encoded according to the contained type. *List[Int]* example: .. code:: javascript "lstInt": [ "foo", "bar", … ] *List[Object]* example: .. code:: javascript "lstObj": [ { "a": 1, "b": true }, { "a": 2, "b": false }, … ] Empty list example: .. code:: javascript "lstObj": [] *Map[…]* **JSON:** As a JSON object with each field value encoded according to the contained type. *Map[Int]* example: .. code:: javascript "mapInt": { "foo": 1, "bar": 2, … } *Map[Object]* example: .. code:: javascript "mapObj": { "foo": { "a": 1, "b": true }, "bar": { "a": 2, "b": false }, … } Empty map example: .. code:: javascript "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.