Versioning

The Kashu API changes without breaking code that already works. Each path starts /v1, and within v1 the API has dated versions. The current version is 2026-11-06.

Your key pins a version

A key answers in the version that was current when you made it, which the key shows as api_version. Rolling a key keeps its version. So a new version never changes the answers your running code gets.

Every answer to a request made with a key carries a Kashu-Version header that names the version its body is in.

Ask for another version

To try another version before you move to it, send its date in the Kashu-Version header:

curl https://api.kashupay.com/v1/payments \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Kashu-Version: 2026-11-06"

A date that names no version answers 400 api_version_invalid.

Webhook endpoints pin a version too

A webhook endpoint keeps the version of the request that made it, as api_version. Kashu renders each event it sends to that endpoint in that version, and the event's own api_version says which.

What makes a new version

A change that could break working code ships as a new dated version, and older versions keep their shapes. Removing or renaming a field and changing a field's type are such changes.

A change that only adds comes to every version: a new endpoint, a new optional parameter, a new field in a response, or a new event type. Write your code to ignore fields and event types it does not know.