Create Payment Intent

Intro

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

This endpoint does not create a 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, a hosted checkout 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.

Context

Use this endpoint (or its /payments/intents alias) for a catalog-backed, embedded checkout. If your product lives outside Khaime’s catalog — e.g. WooCommerce or a custom platform — use Create Charge instead, which needs no product_id. Like Create Charge, the resulting payment is routed by currency (see Gateway Routing), can be made recurring via subscription_frequency_key (see Subscriptions), and its outcome is confirmed over webhooks — Get Session does not currently work as a status check for intents created here.

Hows

Request body

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.

string

required

3-letter ISO currency code the customer pays in.

integer

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

object

required

Show Customer fields

string

required

Customer’s email — required.

string

First name.

string

Last name.

string

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

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.

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. See Subscriptions for the full list of valid keys.

Recurring billing here is handled by Khaime’s own billing system — subscription_id fields in the response are always null since renewals are managed internally.

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.

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.

string

Redirect URL if the customer abandons a Paystack redirect payment.

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_...",
    "payment_intent_id": "pi_3Abc...",
    "subscription_id": null,
    "paystack_reference": null,
    "client_secret": "pi_3Abc_secret_Xyz",
    "merchant_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 the embedded 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.
`merchant_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 Khaime 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

Get Session does not work as a status check for intents created through this route. This response has no transaction_id yet — that only exists once payment completes. Use webhooks (payment.succeeded / payment.failed) to learn the transaction id and confirm payment status; from then on you can also call Get Transaction to check status on demand.

curl -X POST https://api.khaime.com/api/v1/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/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"
    }
  }'

Whys

/payments/sessions and /payments/intents are kept as aliases of the same handler rather than split into two endpoints because they answer the same question — “start a checkout for this catalog product” — and existing partner integrations reference both names from earlier iterations of this API. product_id is validated against your API key’s live/sandbox environment (not just ownership) so a sandbox key can never accidentally create a live-money intent against a live product.

Why nots

This is not the endpoint for products that don’t exist in Khaime’s catalog — use Create Charge for that.
It does not create a real Stripe Checkout Session — despite the endpoint name, there is no checkout.stripe.com URL in the response.
product_name-only lookup does not work today, despite being accepted by the validation schema — always send product_id.
There is no way to poll status using the intent itself — Get Session doesn’t work here. Rely on webhooks to learn the transaction id, then Get Transaction if you also want on-demand polling after that.

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Marketplace

Intro

Context

Hows

Request body

Response

Error codes

Checking payment status

Whys

Why nots

​Intro

​Context

​Hows

​Request body

​Response

​Error codes

​Checking payment status

​Whys

​Why nots

Intro

Context

Hows

Request body

Response

Error codes

Checking payment status

Whys

Why nots