API Versioning

How webhook payload versioning works and how to migrate between versions.

Webhook API Versioning

Khaime uses date-based versioning for webhook payloads. This ensures partners can adopt new payload structures at their own pace without breaking existing integrations.

How Versions Work

• api_version is a date string (e.g., "2026-03-27") stored on each API key record.
• The version is included in the webhook body (api_version field) and the X-Khaime-Api-Version response header.
• New partners are assigned the latest version at key creation.
• Existing partners keep their current version until they explicitly opt in to a newer one.

What Triggers a New Version

Change type	New version required?
New optional field added to an existing object	No
New event type added	No
Field renamed or removed	Yes
Field type changed (e.g., number to string)	Yes
Nested object restructured	Yes

Adding new optional fields or new event types is non-breaking — your integration should handle unknown fields gracefully.

Migrating to a New Version

Update your API key’s version via the API:

curl -X PUT https://api.khaime.com/api/v1/partner/api-keys/YOUR_KEY_ID/webhook \
  -H "x-id-key: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_version": "2026-03-27"}'

Once updated, all subsequent webhook deliveries will use the new payload structure.

Migration Guide: Pre-2026-03-27 to 2026-03-27

The 2026-03-27 version introduces structured multi-currency amounts, expanded event types, and richer object payloads.

Key Changes

Area	Before	After (2026-03-27)
Amounts	Flat amount and currency fields	Structured MulticurrencyBreakdown with customer_paid, merchant_gross, merchant_net, and fees
Customer	Nested under data.customer with paid_amount / paid_currency	Clean customer object; payment amounts moved to amounts
Product info	Flat product_id in data, details in transaction_details	Structured product object with id, title, type
Transaction details	transaction_details sub-object	Fields promoted to top level (payment_type, gateway)
Envelope	No api_version or business_id	Both always present

Event Mapping

Previous event	New event	Payload changes
payment.succeeded	payment.succeeded	Amounts moved into MulticurrencyBreakdown; product, installment fields added
payment.failed	payment.failed	Same restructuring
subscription.created	subscription.created	plan, current_period, trial fields added
refund.completed	payment.refunded	Now part of the payment.* group with a refund sub-object
(new)	wallet.credited	Wallet operations now fire events
(new)	wallet.debited	Wallet operations now fire events
(new)	settlement.*	Full payout lifecycle tracking
(new)	dispute.*	Dispute lifecycle events
(new)	order.*	Physical product fulfillment tracking

Example: payment.succeeded

Before (pre-2026-03-27)

{
  "event_type": "payment.succeeded",
  "event_id": "evt_123456_1708900000000",
  "occurred_at": "2026-01-16T21:05:00.000Z",
  "is_live": true,
  "data": {
    "transaction_id": "456",
    "amount": 5000,
    "currency": "USD",
    "status": "success",
    "customer": {
      "email": "[e-mail]",
      "first_name": "Jane",
      "last_name": "Doe",
      "paid_amount": 5000,
      "paid_currency": "USD"
    },
    "transaction_details": {
      "payment_type": "one_time",
      "product_type": "digital",
      "product_title": "Premium Plan",
      "payment_gateway": "stripe",
      "created_at": "2026-01-16T21:00:00.000Z"
    }
  }
}