API Versioning

​

How Versioning Works

https://{base_url}/card/v4/{id}

• Each endpoint has its own version. There is no single version for the platform or for a whole API, and you select the version only through the URL path. One API can have current endpoints on different versions — for example, the Card API has multi-application card endpoints on v1, plastic endpoints on v3 and card endpoints on v4. Use the version shown for each endpoint in the API reference.
• Compatible changes stay in the current version. We add them to the existing endpoint without changing its URL, and publish them in the Release Notes.
• Breaking changes get a new version. We release the changed endpoint under a new version in the path, and mark the previous version as deprecated.

​

Compatible and Breaking Changes

​

Compatible Changes

• Adding new APIs or endpoints.
• Adding new optional parameters to existing requests.
• Adding new attributes to existing responses and webhook payloads.
• Adding new values to existing enums, in responses, webhook payloads and requests.
• Changing the order of attributes in responses and webhook payloads.
• Changing human-readable text, such as the message attribute of error responses.

​

Breaking Changes

• Removing or renaming an endpoint, parameter or attribute.
• Changing the data type or format of an existing parameter or attribute — for example, from a string to an object.
• Adding a new required parameter, or making an optional parameter required.
• Removing an enum value, or changing the meaning of an existing value.
• Changing the HTTP method or path of an endpoint.
• Changing the HTTP status code returned for an existing outcome.
• Adding validation that rejects requests that were previously valid.
• Changing the behaviour applied when an optional parameter is omitted.

​

Integration Recommendations

• Ignore unknown attributes. Configure your JSON parser to skip attributes your data model doesn’t define, rather than fail. Some libraries fail by default — for example, Jackson in Java throws an exception unless you disable FAIL_ON_UNKNOWN_PROPERTIES.
• Handle unknown enum values. Map a value you don’t recognise to a fallback, such as UNKNOWN, instead of failing the whole response. Decide what the safe behaviour is for an unknown value — for example, don’t treat a card with an unrecognised status as usable. Log the value so you can check the Release Notes and update your mapping. Avoid exhaustive switch statements without a default branch.
• Validate leniently. If you validate responses or webhook payloads against the OpenAPI specification, allow additional attributes and additional enum values.
• Read attributes by name. Don’t depend on the order of attributes in a JSON object.
• Expect optional attributes to be missing or null. For example, merchantZipCode is null when the card Scheme doesn’t provide it.
• Use error codes, not error messages. Base your error handling on the HTTP status code and the errorCode and errorType attributes of the error response. The message attribute is for people and can change.
• Treat identifiers as opaque. Store identifiers such as cardId and customerId exactly as returned, and don’t derive meaning from their structure.
• Follow the Release Notes. Subscribe to the RSS feed of the Release Notes to learn about new attributes, values and versions, and to plan your move away from deprecated endpoints.

ObjectMapper mapper = new ObjectMapper()
    .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
    .configure(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE, true);

enum CardStatus {
    CARD_OK,
    CARD_BLOCKED,
    SUSPECTED_FRAUD,
    CARD_CLOSED_DUE_TO_FRAUD,
    CARD_NO_RENEWAL,
    CARD_LOST,
    CARD_STOLEN,
    CARD_CLOSED,
    @JsonEnumDefaultValue
    UNKNOWN
}