Formats dictate the precise formatting of values atop the basic JSON data types (string, numeric, boolean, array, object), aligning with the properties mandated by our API.

This document section delineates the recurrent formats through contextual examples, serving as a reference for the API specifications highlighted for each request/response transactions.

Int

In JSON, there is no distinct separation between integers and floating-point numbers. This format is employed to indicate that the numeric value must be without any decimal places.

Example

    {
      "integer": 111
    }

Enum

Enums are a collection of pre-defined string values, written in fully capitalized form, with multiple words separated by underscores "_".

Example

    {
      "enums": ["BAZ", "FOO_BAR"]
    }

Datetime

All datetimes/timestamps will be expressed as RFC3339 strings, consistently in UTC format. Whenever a property necessitates a datetime representation, it will be indicated using this format.

Example

   {
     "created_at": "2023-07-20T15:15:37+00:00"
   }

Date

Date is a string formatted as YYYY-MM-DD, it represents a date without its time part. Used for things such as date of birth, documents expiry dates etc.

Example

    {
      "date_of_birth": "1912-06-23"
    }

Monetary amount

All monetary values will be represented as decimals wrapped within strings. This approach is adopted to prevent any possible misinterpretation caused by floating-point rounding. Many JSON unmarshallers (e.g. javascript) will unmarshal JSON numbers to IEEE 754 double-precision floating point numbers, potentially leading to a silent loss of precision.

Example

    {
    	"amount": "99.99"
    }

Currency

Currencies are represented as ISO 4217 enums.

Example

   {
   	"currencies": ["GBP", "USD", "KES"]
   }

Country

Countries are represented as ISO 3166-1 alpha-2 enums.

Example

  {
  	"countries": ["GB", "US", "KE"]
  }

Phone number

Phone numbers are strings represented as E.164

Example

  {
  	"uk_number": "+442071838750"
  }