Webhooks
Khaime sends HTTP POST requests to your webhook URL when events occur across the full lifecycle of payments, subscriptions, wallet operations, settlements, disputes, and physical order fulfillment. This is the most reliable way to track transaction state — don’t rely solely on redirect callbacks.Setup
- Go to Khaime Dashboard → Settings → API
- Set your Webhook URL (e.g.,
https://yoursite.com/webhooks/khaime) - Copy your Webhook Secret (
whsec_...)
Envelope Structure
Every webhook delivery shares the same outer envelope regardless of event type:The
event_id is the idempotency key. You must store processed event_id values and skip duplicates — retries reuse the same event_id.Webhook Headers
Every webhook request includes these headers:Delivery
Shared Data Types
These types appear across multiple event payloads.MoneyAmount
All monetary values are in the smallest currency unit (cents for USD, kobo for NGN). Never floats.MulticurrencyBreakdown
Present on payment and order events. Provides a full breakdown of amounts, fees, and currency conversion.conversion is omitted and customer_paid equals merchant_gross.
Customer
id field is present only if the customer has a platform account.
