Skip to main content

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.

​
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 typeNew version required?
New optional field added to an existing objectNo
New event type addedNo
Field renamed or removedYes
Field type changed (e.g., number to string)Yes
Nested object restructuredYes
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

AreaBeforeAfter (2026-03-27)
AmountsFlat amount and currency fieldsStructured MulticurrencyBreakdown with customer_paid, merchant_gross, merchant_net, and fees
CustomerNested under data.customer with paid_amount / paid_currencyClean customer object; payment amounts moved to amounts
Product infoFlat product_id in data, details in transaction_detailsStructured product object with id, title, type
Transaction detailstransaction_details sub-objectFields promoted to top level (payment_type, gateway)
EnvelopeNo api_version or business_idBoth always present

​
Event Mapping

Previous eventNew eventPayload changes
payment.succeededpayment.succeededAmounts moved into MulticurrencyBreakdown; product, installment fields added
payment.failedpayment.failedSame restructuring
subscription.createdsubscription.createdplan, current_period, trial fields added
refund.completedpayment.refundedNow part of the payment.* group with a refund sub-object
(new)wallet.creditedWallet operations now fire events
(new)wallet.debitedWallet 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"
    }
  }
}