curl -X POST https://api.khaime.com/api/v1/partner/payments/sessions \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 501,
    "currency": "USD",
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }'

curl -X POST https://api.khaime.com/api/v1/partner/payments/sessions \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 501,
    "currency": "USD",
    "subscription_frequency_key": "monthly",
    "customer": {
      "email": "jane@example.com"
    }
  }'

POST

payments

sessions

curl -X POST https://api.khaime.com/api/v1/partner/payments/sessions \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 501,
    "currency": "USD",
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }'

curl -X POST https://api.khaime.com/api/v1/partner/payments/sessions \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 501,
    "currency": "USD",
    "subscription_frequency_key": "monthly",
    "customer": {
      "email": "jane@example.com"
    }
  }'

Create Payment Intent

Create a payment intent tied to a product in your Khaime catalog. Returns a client_secret (Stripe) or authorization_url (Paystack) for an embedded checkout on your own page, plus a ready-made payment_url to Khaime’s hosted checkout page if you’d rather redirect instead of embedding.

This endpoint does not create a Stripe-hosted Checkout Session. POST /payments/sessions and POST /payments/intents call the exact same handler and return the exact same response shape — they are aliases, not different flows. Older versions of this page described a hosted-Checkout-Session response (session_id, stripe_session_id, a checkout.stripe.com URL) — that flow was replaced by the PaymentIntent/Direct Charge model below and is no longer reachable through this route. If you have integration code built against the old shape, update it to read intent_id / client_secret instead.

Use this endpoint (or its /payments/intents alias) when you want a product-based checkout with Stripe Payment Element or Paystack’s inline popup embedded on your own page. If you don’t have the product in Khaime’s catalog — e.g. WooCommerce/custom platforms where the product lives elsewhere — use Create Charge instead.

Request Body

product_id

integer

required

ID of an existing, published Khaime product owned by your business. Must match your API key’s environment (a sandbox key can only resolve sandbox products, a live key only live products) — otherwise 404.

The Joi schema also accepts product_name as a fallback lookup field, but the controller currently rejects any request missing product_id before that fallback runs — product_name-only requests always fail with a “Missing required fields” error today. Always pass product_id.

currency

string

required

3-letter ISO currency code the customer pays in.

amount

integer

Override amount in smallest currency unit. If omitted, the product’s catalog price is used.

customer

object

required

Show Customer fields

string

required

Customer’s email — required.

first_name

string

First name.

last_name

string

Last name.

country

string

2-letter ISO country code. Used for gateway/fee routing.

payment_gateway

string

Force a specific gateway instead of Khaime’s automatic currency-based routing. Only stripe or paystack are accepted — you cannot force startbutton or flutterwave through this field.

subscription_frequency_key

string

Set to make this a recurring payment (e.g. monthly, yearly). Presence of this field (or subscription_plan_key) is what makes the intent a subscription — there is no separate boolean flag.

Recurring billing here is handled by Khaime’s own billing cron, not Stripe Subscriptions — stripe_subscription_id in the response is always null.

subscription_plan_key

string

Alternative to subscription_frequency_key when the product has named plans configured. If the plan has exactly one frequency option, it’s auto-selected.

success_url

string

Where the customer lands after paying via Paystack’s redirect flow. Threaded into Paystack’s callback_url so the buyer returns to your confirmation page directly.

cancel_url

string

Redirect URL if the customer abandons a Paystack redirect payment.

metadata

object

Custom key-value pairs. No scalar-type enforcement is applied server-side — unlike Create Charge, you can pass nested values here, but avoid it: nested metadata can still fail downstream if the selected gateway’s API rejects non-string values.

Response

{
  "success": true,
  "message": "Payment intent created successfully",
  "data": {
    "intent_id": "intent_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "payment_gateway": "stripe",
    "publishable_key": "pk_test_...",
    "stripe_payment_intent_id": "pi_3Abc...",
    "stripe_subscription_id": null,
    "paystack_reference": null,
    "client_secret": "pi_3Abc_secret_Xyz",
    "stripe_account_id": "acct_1ABC...",
    "authorization_url": null,
    "payment_url": "https://pay.khaime.com/checkout?data=eyJhbW91bnQ...",
    "expires_at": "2026-01-16T22:00:00.000Z",
    "amount": 5320,
    "currency": "USD",
    "status": "pending",
    "payment_type": "one_time",
    "fee_details": {
      "base_product_price": 5000,
      "transaction_fee": 320,
      "total_amount": 5320,
      "customer_pays_fees": true,
      "is_international": false
    },
    "product": {
      "id": 501,
      "title": "Premium Plan",
      "description": "Monthly premium access",
      "type": "digital"
    },
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }
}

Use client_secret + publishable_key to mount Stripe Payment Element on your own page. For Paystack, use authorization_url (present instead of client_secret when payment_gateway resolves to paystack). Or simply redirect the customer to payment_url — Khaime’s own hosted checkout page — if you don’t want to embed anything.

Response Fields

Field	Type	Description
`intent_id`	string	Khaime’s identifier for this intent (`intent_...`). Not a `session_id` — no session object is created.
`stripe_account_id`	string \| null	Connected account ID when the merchant uses direct charge. `null` on the platform account.
`payment_url`	string	Khaime’s own hosted checkout page (not Stripe Checkout). Overridable per-merchant via `custom_payment_url`.
`expires_at`	string	Fixed 30 minutes from creation.
`subscription`	object	Present only when `subscription_frequency_key`/`subscription_plan_key` was set.

Error Codes

Status	Error Code	Cause
`422`	`VALIDATION_FAILED`	Schema validation failed (e.g. missing `product_id`, invalid `payment_gateway` value, `customer.country` not 2 letters).
`400`	`VALIDATION_MISSING_FIELD`	`product_id`, `currency`, or `customer.email` missing, or no `amount` could be resolved (no override and product has no price).
`404`	`BUSINESS_NOT_FOUND`	Authenticated merchant record not found.
`404`	`PRODUCT_NOT_FOUND`	`product_id` doesn’t exist, isn’t yours, or doesn’t match your API key’s live/sandbox environment.
`400`	`PAYMENT_CURRENCY_UNSUPPORTED`	`currency` isn’t supported by any gateway.
`400`	`PAYMENT_INTENT_FAILED`	Unhandled error during intent creation (gateway call failed, etc).

Checking Payment Status

There is currently no working polling endpoint for intents created through this route — see Get Session for why. Use webhooks (payment.succeeded / payment.failed) to confirm payment status.

curl -X POST https://api.khaime.com/api/v1/partner/payments/sessions \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 501,
    "currency": "USD",
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }'

curl -X POST https://api.khaime.com/api/v1/partner/payments/sessions \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 501,
    "currency": "USD",
    "subscription_frequency_key": "monthly",
    "customer": {
      "email": "jane@example.com"
    }
  }'

Create Charge Get Session

API Reference

Account

Products & Pricing

Payments

Subscriptions

Marketplace

B2B Commerce

Create Payment Intent

Create Payment Intent

Request Body

Response

Response Fields

Error Codes

Checking Payment Status

​Create Payment Intent

​Request Body

​Response

​Response Fields

​Error Codes

​Checking Payment Status

Create Payment Intent

Request Body

Response

Response Fields

Error Codes

Checking Payment Status