> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**               |

<Note>
  Adding new optional fields or new event types is **non-breaking** — your integration should handle unknown fields gracefully.
</Note>

## Migrating to a New Version

Update your API key's version via the API:

```bash theme={null}
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

<CodeGroup>
  ```json Before (pre-2026-03-27) theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json After (2026-03-27) theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>