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:
| Type | Description |
|---|---|
| Amount value | Amounts 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 number | Credit/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 value | Card verification values (CVV) are formatted as a string of digits. The value must be 3 or 4 digits long. |
| Country | Country code fields follow the ISO 3166-1 Alpha 2 standard in lowercase. Examples: "es", "us". |
| Currency | Currency code fields follow the ISO 4217 Alpha 3 standard in lowercase. Examples: "eur", "usd". |
| Date | Dates are formatted using the complete date format according to the ISO 8601 standard: "YYYY-MM-DD". Example: "2015-09-01". |
| Date-time | Date-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". |
| ID | Identifiers generated by the API are globally unique. |
| IP address | IP addresses can be formatted as IPv4 or IPv6 format. The IPv4 follows the RFC 791 standard. The IPv6 follows the RFC 4291 standard. |
| Locale | Locale code fields follow the RFC 5646 standard. Example: "en-us". |
| Phone number | Phone 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). |
| State | State 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.