Skip to main content

​
Intro

Khaime handles the full subscription lifecycle — creation, recurring billing, renewals, and cancellation — as an extra field on a normal charge or payment intent request, not a separate API.

​
Context

Subscriptions build directly on Create Charge and Create Payment Intent: add a frequency field to either request and the resulting payment becomes recurring. Recurring charges still go through the same Gateway Routing as one-time payments, and renewal/cancellation events arrive over the same webhook channel used for one-time payments.

​
Hows

Add subscription_frequency_key to your charge or session request:
Presence of subscription_frequency_key (or subscription_plan_key, for products with named pricing tiers) is what makes the charge recurring — there’s no separate boolean flag.

​
Frequencies

Recurring billing is driven by Khaime’s own billing cron, not native Stripe Subscriptions — this keeps behavior identical across Stripe- and Paystack-routed currencies. If you inspect a Stripe-routed response, stripe_subscription_id will be null even for an active subscription.

​
Managing subscriptions

List subscriptions
Get details
Cancel
Customer subscriptions (includes trial info, status, next payment date)

​
Webhook events

  • subscription.created — First payment succeeded, subscription active
  • subscription.renewed — Recurring payment succeeded
  • subscription.payment_failed — A renewal attempt failed
  • subscription.cancelled — Subscription cancelled
  • subscription.expired — Subscription lapsed after failed renewals
  • subscription.trial_started, subscription.trial_ending, subscription.trial_ended — Trial lifecycle events (Stripe-routed subscriptions only — see below)

​
Whys

Subscriptions are a field on the same charge/intent request, rather than a distinct “create subscription” endpoint, so that switching a product between one-time and recurring is a one-field change on the partner’s side, not a different integration path. Billing itself runs on Khaime’s own cron rather than each gateway’s native subscription engine so that renewal behavior, retry logic, and webhook shapes are identical regardless of which gateway a given currency happens to route to.

​
Why nots

  • Paystack-routed subscriptions do not support free trials — trial settings configured on a product are silently ignored when the resolved gateway is Paystack. Trials only apply to Stripe-routed subscriptions.
  • Not every frequency is available on every gateway — Paystack subscriptions are limited to a fixed set of interval lengths (1, 3, 6, and 12 months); Stripe supports arbitrary custom intervals.
  • There’s no endpoint to change an active subscription’s amount or frequency in place — cancel and create a new one instead.