Skip to main content

Message format

Case sensitivity​

  • URLs: case-sensitive for everything after the domain name, includes paths, resorces and query parameters.
  • Headers: field names are case-insensitive and field values are case-sensitive.
  • Request/response body: case-insensitive, we recommend reading the response in the same way.

Encoding​

The content of messages is encoded in UTF-8 (8-bit UCS/Unicode Transformation Format).

Structure​

Request messages can only contain fields defined in the API, otherwise the request will fail with 400 BadRequest (i.e., requests with unrecognized fields are not accepted).

Nulls, empty values, and blank spaces​

  • A field defined as required means that it must be present in the request.
  • An empty string "" or blank space " " in a string field is different from not sending the field at all. An empty string value could only be valid if zero length is allowed for that field.
  • Optional enumeration fields cannot be empty "". If they are specified, their value must be a valid one for that enumeration.
  • Blank spaces are not removed automatically. Length field validations take them into account if present.

A defensive programming approach is recommended to handle the data collected from input introduced by users.

Data types​

Fields formats​

Some of the fields of the API must follow a specific format:

TypeDescription
Amount valueAmounts are formatted using a dot (".") as a decimal separator. The maximum number of decimals depends on the currency used and it is specified according to ISO 4217. It is not needed to specify all decimals, for example €5.00 can be formatted as "5", "5.0" or "5.00".
Card numberCredit/debit card numbers are formatted as a string of digits with no white spaces or dashes. The value must be between 13 and 19 digits long and must fulfill the Luhn check.
Card verification valueCard verification values (CVV) are formatted as a string of digits. The value must be 3 or 4 digits long.
CountryCountry code fields follow the ISO 3166-1 Alpha 2 standard in lowercase. Examples: "es", "us".
CurrencyCurrency code fields follow the ISO 4217 Alpha 3 standard in lowercase. Examples: "eur", "usd".
DateDates are formatted using the complete date format according to the ISO 8601 standard: "YYYY-MM-DD". Example: "2015-09-01".
Date-timeDate-time fields are formatted using the ISO 8601 standard for the combined date and time in UTC: "YYYY-MM-DDThh:mm:ss.sssZ". Example: "2015-09-01T23:59:59.479Z".
IDIdentifiers generated by the API are globally unique.
IP addressIP addresses can be formatted as IPv4 or IPv6 format. The IPv4 follows the RFC 791 standard. The IPv6 follows the RFC 4291 standard.
LocaleLocale code fields follow the RFC 5646 standard. Example: "en-us".
Phone numberPhone numbers can be formatted as international or national numbers. International numbers are formatted using the globalized format of the E.164 standard, and have a "+" character followed by a country code (1 to 3 digits) then followed by a national number (4 to 12 digits). National numbers are formatted as a string of digits (4 to 12 digits). Except from the "+" prefix for international numbers, no character different from a digit (0 to 9) is allowed, in particular, spaces, dashes and parenthesis are not allowed. Examples: +85222333033 (international number, Hong Kong), +60378443696 (international number, Malaysia), 22333033 (national number, no country code specified).
StateState code fields (also used for province/region codes) follow the ISO 3166-2 standard (excluding the country code) in lowercase. Examples: "ny" (for New York, United States), "on" (for Ontario, Canada).

Enumerations​

All API enumerations follow the snake_case naming convention.

Enumerations are extensible and may receive new values in the future. Therefore, please ensure that your code can handle unexpected values in enumeration fields.