Message format
Case sensitivity
- URLs: case-sensitive for everything after the domain name, includes paths, resources 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. |
| Currency | Currency code fields follow the ISO 4217 Alpha 3 standard in lowercase. Examples: "eur", "usd". |
| 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. |
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.