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

{
  "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": "jane@example.com",
      "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"
    }
  }
}

{
  "api_version": "2026-03-27",
  "event_id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "payment.succeeded",
  "occurred_at": "2026-01-16T21:05:00.000Z",
  "is_live": true,
  "business_id": "1042",
  "data": {
    "object": "payment",
    "id": "456",
    "status": "succeeded",
    "payment_type": "one_time",
    "gateway": "stripe",
    "gateway_reference": "ch_abc123",
    "amounts": {
      "customer_paid": { "amount": 5000, "currency": "USD" },
      "merchant_gross": { "amount": 5000, "currency": "USD" },
      "merchant_net": { "amount": 4400, "currency": "USD" },
      "fees": {
        "platform_fee": { "amount": 300, "currency": "USD" },
        "gateway_fee": { "amount": 300, "currency": "USD" },
        "total": { "amount": 600, "currency": "USD" }
      }
    },
    "product": {
      "id": "3046",
      "title": "Premium Plan",
      "type": "digital"
    },
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "created_at": "2026-01-16T21:00:00.000Z",
    "paid_at": "2026-01-16T21:05:00.000Z"
  }
}

Getting Started

Payments

Webhooks

API Versioning

Webhook API Versioning

How Versions Work

What Triggers a New Version

Migrating to a New Version

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

Key Changes

Event Mapping

Example: payment.succeeded

​Webhook API Versioning

​How Versions Work

​What Triggers a New Version

​Migrating to a New Version

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

​Key Changes

​Event Mapping

​Example: payment.succeeded

Webhook API Versioning

How Versions Work

What Triggers a New Version

Migrating to a New Version

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

Key Changes

Event Mapping

Example: payment.succeeded