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 Events Events use dot-notation grouping: {object}.{action}. All events share the same envelope structure — the data field contains the event-specific object documented below.
Event Taxonomy payment.* Event When it fires payment.succeededA charge completed successfully (one-time, subscription, or installment) payment.failedA charge attempt failed payment.refundedA full or partial refund was processed payment.disputedA customer opened a chargeback/dispute
subscription.* Event When it fires subscription.createdA new subscription was initiated subscription.renewedA recurring charge succeeded subscription.payment_failedA renewal charge failed subscription.cancelledSubscription was cancelled (immediately or at period end) subscription.expiredPeriod ended without renewal subscription.trial_startedTrial period began subscription.trial_ending3 days before trial ends (grace notification) subscription.trial_endedTrial period ended (converted or expired)
wallet.* Event When it fires wallet.creditedMerchant wallet was credited (after a successful sale) wallet.debitedWallet was debited (refund issued, dispute hold placed, payout)
settlement.* Event When it fires settlement.initiatedPayout/withdrawal was requested settlement.processingGateway confirmed it is processing settlement.completedFunds confirmed delivered to the merchant’s bank settlement.failedPayout failed at the gateway level
dispute.* Event When it fires dispute.createdDispute was opened dispute.evidence_dueEvidence deadline is approaching dispute.wonDispute resolved in the merchant’s favour dispute.lostDispute resolved against the merchant
order.* (physical products only) Event When it fires order.createdOrder was placed and paid order.shippedShipping label generated, tracking available order.deliveredDelivery confirmed order.refundedOrder-level refund (also fires payment.refunded)
Event Payloads payment.succeeded Fired when a payment is completed successfully.
{ "api_version" : "2026-03-27" , "event_id" : "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "event_type" : "payment.succeeded" , "occurred_at" : "2026-03-27T14:32:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "payment" , "id" : "98234" , "status" : "succeeded" , "payment_type" : "one_time" , "gateway" : "paystack" , "gateway_reference" : "ps_ref_abc123" , "partner_reference" : "order_XYZ" , "amounts" : { "customer_paid" : { "amount" : 5000000 , "currency" : "NGN" }, "merchant_gross" : { "amount" : 306 , "currency" : "USD" }, "merchant_net" : { "amount" : 270 , "currency" : "USD" }, "fees" : { "platform_fee" : { "amount" : 18 , "currency" : "USD" }, "gateway_fee" : { "amount" : 18 , "currency" : "USD" }, "total" : { "amount" : 36 , "currency" : "USD" } }, "conversion" : { "from_currency" : "NGN" , "to_currency" : "USD" , "rate" : 1630.5 , "surcharge_percent" : 1.0 } }, "product" : { "id" : "512" , "title" : "Advanced React Course" , "type" : "self_pace_training" }, "customer" : { "email" : "ada@example.com" , "first_name" : "Ada" , "last_name" : "Obi" }, "metadata" : { "partner_reference" : "order_XYZ" }, "created_at" : "2026-03-27T14:30:00Z" , "paid_at" : "2026-03-27T14:32:00Z" } }
Show Payment object fields
Field Type Description objectstring Always "payment" idstring Transaction ID statusstring succeeded, failed, refunded, or disputedpayment_typestring one_time, subscription, or installmentgatewaystring stripe, paystack, square, paypal, startbutton, or walletgateway_referencestring Gateway’s transaction/charge ID session_idstring Cart identifier (optional) partner_referencestring Value passed in metadata.partner_reference at session creation (optional) amountsobject MulticurrencyBreakdown productobject Product id, title, and type (optional) subscription_idstring Present when payment_type is subscription installmentobject split_number and total_splits for installment paymentscoupon_discountobject MoneyAmount if a coupon was appliedtaxobject MoneyAmount if tax was chargedshippingobject Shipping cost, tracking number, and carrier (physical products) refundobject Present on payment.refunded only (see below) customerobject Customer email, first_name, last_name, id metadataobject Partner-supplied fields (internal keys stripped) created_atstring ISO 8601 — when the payment was initiated paid_atstring ISO 8601 — when the charge was confirmed (null on failed)
payment.failed Fired when a payment attempt fails. Same structure as payment.succeeded with status: "failed" and paid_at: null.
{ "api_version" : "2026-03-27" , "event_id" : "evt_789_failed" , "event_type" : "payment.failed" , "occurred_at" : "2026-03-27T14:35:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "payment" , "id" : "98235" , "status" : "failed" , "payment_type" : "one_time" , "gateway" : "stripe" , "gateway_reference" : "ch_failed_abc" , "amounts" : { "customer_paid" : { "amount" : 5000 , "currency" : "USD" }, "merchant_gross" : { "amount" : 5000 , "currency" : "USD" }, "merchant_net" : { "amount" : 0 , "currency" : "USD" }, "fees" : { "platform_fee" : { "amount" : 0 , "currency" : "USD" }, "gateway_fee" : { "amount" : 0 , "currency" : "USD" }, "total" : { "amount" : 0 , "currency" : "USD" } } }, "customer" : { "email" : "jane@example.com" }, "created_at" : "2026-03-27T14:34:00Z" , "paid_at" : null } }
payment.refunded Fired when a full or partial refund is processed.
{ "api_version" : "2026-03-27" , "event_id" : "evt_refund_456" , "event_type" : "payment.refunded" , "occurred_at" : "2026-03-28T10:00:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "payment" , "id" : "98234" , "status" : "refunded" , "payment_type" : "one_time" , "gateway" : "paystack" , "gateway_reference" : "ps_ref_abc123" , "amounts" : { "customer_paid" : { "amount" : 5000000 , "currency" : "NGN" }, "merchant_gross" : { "amount" : 306 , "currency" : "USD" }, "merchant_net" : { "amount" : 270 , "currency" : "USD" }, "fees" : { "platform_fee" : { "amount" : 18 , "currency" : "USD" }, "gateway_fee" : { "amount" : 18 , "currency" : "USD" }, "total" : { "amount" : 36 , "currency" : "USD" } } }, "refund" : { "id" : "ref_001" , "refund_amount" : { "amount" : 270 , "currency" : "USD" }, "is_partial" : false , "reason" : "Customer requested" }, "customer" : { "email" : "ada@example.com" , "first_name" : "Ada" , "last_name" : "Obi" }, "created_at" : "2026-03-27T14:30:00Z" , "paid_at" : "2026-03-27T14:32:00Z" } }
payment.disputed Fired when a customer opens a chargeback or dispute. Same payment structure with status: "disputed".
subscription.created Fired when a new subscription is initiated.
{ "api_version" : "2026-03-27" , "event_id" : "evt_sub_create_001" , "event_type" : "subscription.created" , "occurred_at" : "2026-03-27T15:00:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "subscription" , "id" : "psub_abc123" , "status" : "active" , "product" : { "id" : "512" , "title" : "Premium Membership" , "type" : "digital" }, "plan" : { "interval" : "monthly" , "amount" : { "amount" : 2999 , "currency" : "USD" } }, "current_period" : { "start" : "2026-03-27T15:00:00Z" , "end" : "2026-04-27T15:00:00Z" }, "customer" : { "email" : "jane@example.com" , "first_name" : "Jane" , "last_name" : "Doe" }, "created_at" : "2026-03-27T15:00:00Z" } }
Show Subscription object fields
Field Type Description objectstring Always "subscription" idstring Subscription ID (product_subscription_id) statusstring active, trialing, past_due, cancelled, or expiredproductobject Product id, title, and type (optional) plan.intervalstring weekly, monthly, quarterly, annually, etc.plan.amountobject MoneyAmount in merchant’s settlement currencycurrent_periodobject start and end ISO 8601 timestampstrialobject start and end timestamps (present during trials)latest_payment_idstring Present on renewed and payment_failed events amountsobject MulticurrencyBreakdown (present on renewed and payment_failed)cancel_at_period_endboolean Whether cancellation takes effect at period end cancellation_reasonstring Present on subscription.cancelled customerobject Customer details metadataobject Partner-supplied fields created_atstring ISO 8601
subscription.renewed Fired when a recurring charge succeeds. Includes latest_payment_id and amounts with the renewal payment breakdown.
subscription.payment_failed Fired when a renewal charge fails. Subscription status changes to past_due.
subscription.cancelled Fired when a subscription is cancelled (immediately or at period end). Includes cancellation_reason if provided.
subscription.expired Fired when the subscription period ends without renewal.
subscription.trial_started Fired when a trial period begins. Subscription status is trialing and the trial object is present.
subscription.trial_ending Fired 3 days before a trial ends — a grace notification to prompt conversion.
subscription.trial_ended Fired when the trial period ends (whether the subscription converted to paid or expired).
wallet.credited Fired when the merchant wallet is credited (e.g., after a successful sale).
{ "api_version" : "2026-03-27" , "event_id" : "evt_wallet_credit_001" , "event_type" : "wallet.credited" , "occurred_at" : "2026-03-27T14:32:05Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "wallet" , "id" : "wt_ref_00112" , "type" : "credit" , "reason" : "sale" , "amount" : { "amount" : 4640000 , "currency" : "NGN" }, "balance_after" : { "amount" : 12450000 , "currency" : "NGN" }, "related_payment_id" : "98234" , "occurred_at" : "2026-03-27T14:32:05Z" } }
Show Wallet object fields
Field Type Description objectstring Always "wallet" idstring Wallet transaction reference typestring credit or debitreasonstring sale, refund_issued, dispute_hold, dispute_released, payout, or adjustmentamountobject MoneyAmount credited or debitedbalance_afterobject Wallet balance after this operation original_amountobject Present when currency conversion occurred (e.g., NGN sale → USD wallet) conversionobject from_currency, to_currency, rate — present on cross-currency operationsrelated_payment_idstring Transaction ID if from a sale or refund related_dispute_idstring Dispute ID if from a chargeback hold/release related_settlement_idstring Withdrawal ID if from a payout metadataobject Partner-supplied fields occurred_atstring ISO 8601
wallet.debited Fired when the merchant wallet is debited (refund issued, dispute hold placed, or payout). Same structure as wallet.credited with type: "debit".
settlement.initiated Fired when a payout or withdrawal is requested.
{ "api_version" : "2026-03-27" , "event_id" : "evt_settle_001" , "event_type" : "settlement.initiated" , "occurred_at" : "2026-03-27T09:00:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "settlement" , "id" : "wd_00445" , "status" : "initiated" , "gateway" : "paystack" , "payout_method" : "transfer" , "requested" : { "amount" : 10000000 , "currency" : "NGN" }, "fee" : { "amount" : 53000 , "currency" : "NGN" }, "settled" : { "amount" : 9947000 , "currency" : "NGN" }, "initiated_at" : "2026-03-27T09:00:00Z" } }
Show Settlement object fields
Field Type Description objectstring Always "settlement" idstring Withdrawal or wallet transaction ID statusstring initiated, processing, completed, or failedgatewaystring paystack, stripe, startbutton, or gravvpayout_methodstring transfer (platform pushes funds) or payout (gateway pays directly to bank)requestedobject MoneyAmount the merchant requestedfeeobject Settlement/transfer fee settledobject Actual amount sent (requested - fee) cross_currencyobject Present when wallet currency differs from bank currency (see example below) initiated_atstring ISO 8601 completed_atstring Present on settlement.completed failure_reasonstring Present on settlement.failed metadataobject Partner-supplied fields
settlement.completed Fired when funds are confirmed delivered to the merchant’s bank.
{ "api_version" : "2026-03-27" , "event_id" : "evt_settle_complete_001" , "event_type" : "settlement.completed" , "occurred_at" : "2026-03-27T11:45:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "settlement" , "id" : "wd_00445" , "status" : "completed" , "gateway" : "paystack" , "payout_method" : "transfer" , "requested" : { "amount" : 10000000 , "currency" : "NGN" }, "fee" : { "amount" : 53000 , "currency" : "NGN" }, "settled" : { "amount" : 9947000 , "currency" : "NGN" }, "initiated_at" : "2026-03-27T09:00:00Z" , "completed_at" : "2026-03-27T11:45:00Z" } }
Cross-currency settlement example (USD wallet to NGN bank account):{ "data" : { "object" : "settlement" , "id" : "wd_00446" , "status" : "completed" , "gateway" : "paystack" , "payout_method" : "transfer" , "requested" : { "amount" : 50000 , "currency" : "USD" }, "fee" : { "amount" : 500 , "currency" : "USD" }, "settled" : { "amount" : 49500 , "currency" : "USD" }, "cross_currency" : { "source" : { "amount" : 49500 , "currency" : "USD" }, "destination" : { "amount" : 80752500 , "currency" : "NGN" }, "rate" : 1631.36 }, "initiated_at" : "2026-03-27T09:00:00Z" , "completed_at" : "2026-03-27T12:10:00Z" } }
settlement.processing Fired when the gateway confirms the payout is being processed.
settlement.failed Fired when a payout fails at the gateway level. Includes failure_reason.
dispute.created Fired when a dispute is opened on a payment.
{ "api_version" : "2026-03-27" , "event_id" : "evt_dispute_001" , "event_type" : "dispute.created" , "occurred_at" : "2026-03-28T09:00:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "dispute" , "id" : "disp_001" , "status" : "needs_response" , "reason" : "product_not_received" , "gateway" : "stripe" , "gateway_dispute_id" : "dp_abc123" , "disputed_amount" : { "amount" : 5000 , "currency" : "USD" }, "chargeback_fee" : { "amount" : 1500 , "currency" : "USD" }, "hold_amount" : { "amount" : 6500 , "currency" : "USD" }, "related_payment_id" : "98234" , "evidence_due_by" : "2026-04-11T23:59:59Z" , "customer" : { "email" : "ada@example.com" , "first_name" : "Ada" , "last_name" : "Obi" }, "occurred_at" : "2026-03-28T09:00:00Z" } }
Show Dispute object fields
Field Type Description objectstring Always "dispute" idstring Dispute record ID statusstring needs_response, funds_withdrawn, under_review, won, lost, or acceptedreasonstring fraudulent, product_not_received, duplicate, etc.gatewaystring Gateway where the dispute was filed gateway_dispute_idstring Gateway’s dispute ID disputed_amountobject MoneyAmount being disputedchargeback_feeobject Fee charged by the gateway for the dispute hold_amountobject Total held from merchant wallet (disputed_amount + chargeback_fee) related_payment_idstring Transaction ID of the original charge evidence_due_bystring ISO 8601 deadline for submitting evidence resolutionstring won or lost — present on dispute.won and dispute.lostcustomerobject Customer details occurred_atstring ISO 8601
dispute.evidence_due Fired when the evidence deadline is approaching.
dispute.won Fired when the dispute is resolved in the merchant’s favour. Held funds are released.
dispute.lost Fired when the dispute is resolved against the merchant.
order.created Fired when a physical product order is placed and paid.
{ "api_version" : "2026-03-27" , "event_id" : "evt_order_001" , "event_type" : "order.created" , "occurred_at" : "2026-03-27T16:00:00Z" , "is_live" : true , "business_id" : "1042" , "data" : { "object" : "order" , "id" : "98240" , "status" : "created" , "amounts" : { "customer_paid" : { "amount" : 7500 , "currency" : "USD" }, "merchant_gross" : { "amount" : 7500 , "currency" : "USD" }, "merchant_net" : { "amount" : 6900 , "currency" : "USD" }, "fees" : { "platform_fee" : { "amount" : 300 , "currency" : "USD" }, "gateway_fee" : { "amount" : 300 , "currency" : "USD" }, "total" : { "amount" : 600 , "currency" : "USD" } } }, "product" : { "id" : "800" , "title" : "Wireless Headphones" , "type" : "physical_product" }, "shipping" : {}, "customer" : { "email" : "jane@example.com" , "first_name" : "Jane" , "last_name" : "Doe" , "shipping_address" : { "line1" : "123 Main St" , "city" : "Austin" , "state" : "TX" , "postal_code" : "78701" , "country" : "US" } }, "created_at" : "2026-03-27T16:00:00Z" } }
Field Type Description objectstring Always "order" idstring Transaction ID of the purchase statusstring created, shipped, delivered, or refundedamountsobject MulticurrencyBreakdown productobject Product id, title, and type (always physical_product) shipping.carrierstring Shipping carrier name shipping.tracking_numberstring Tracking number (from order.shipped onwards) shipping.tracking_urlstring URL to track the shipment shipping.estimated_deliverystring ISO 8601 estimated delivery date shipping.shipped_atstring ISO 8601 (from order.shipped onwards) shipping.delivered_atstring ISO 8601 (on order.delivered) customer.shipping_addressobject line1, line2, city, state, postal_code, country (ISO 3166-1 alpha-2)refund_idstring Present on order.refunded metadataobject Partner-supplied fields created_atstring ISO 8601
order.shipped Fired when a shipping label is generated and tracking is available. Includes shipping.tracking_number, shipping.carrier, and shipping.shipped_at.
order.delivered Fired when delivery is confirmed. Includes shipping.delivered_at.
order.refunded Fired on an order-level refund. Also fires a payment.refunded event for the associated payment. 