Skip to main content
POST

Intro

Create a payment session for a single product in your Khaime catalog. Returns a token for embedded checkout or a payment_url for redirect-based checkout.
POST /payments/sessions and POST /payments/intents are aliases — both work for single-product checkout. For multi-item carts, use Create Payment Intent instead.

Context

Use this endpoint for single-product catalog-backed checkout. For different use cases, see:

Need Multi-Item Cart Checkout?

For carts with multiple products, shipping addresses, or digital product bundles, use the Commerce Payment Intent endpoint which supports cart arrays and delivery_details.
Payments are automatically routed to the optimal provider based on currency (see Gateway Routing). Recurring payments are supported via subscription_frequency_key (see Subscriptions).
Payment outcomes are confirmed via webhooks. Do not poll for status.

Request

Request body

integer
required
ID of an existing, published Khaime product owned by your business. Must match your API key’s environment (sandbox key → sandbox products, live key → live products).
string
required
3-letter ISO currency code the customer pays in (e.g., USD, NGN, EUR).
integer
Override amount in smallest currency unit (cents/kobo). If omitted, the product’s catalog price is used.
object
required
string
Set to make this a recurring payment (e.g., monthly, yearly). See Subscriptions for valid keys.
string
Alternative to subscription_frequency_key when the product has named plans configured.
object
{ "enabled": true } takes only the first installment of a product sold in installments and opens an installment plan. The response is then the Installment Checkout response instead of a session. See Installments.
string
Set to "url" to receive only a redirect URL instead of a token. Default returns a token for embedded checkout.
string
Where the customer lands after completing payment via redirect flow.
string
Redirect URL if the customer abandons the payment.
object
Custom key-value pairs attached to the payment.

Response


Accepting Payments

Once you receive the token from the API, you need to render a payment form for your customer. There are two ways to do this: Embed the checkout directly in your app for the best user experience. Your customers stay on your site throughout the payment flow.
1

Install @khaime/react

Install the Khaime React SDK in your project:
See the full React SDK documentation for detailed setup instructions and all available options.
2

Render the Checkout Component

Import KhaimeCheckout and pass the token from the API response:
3

Handle the Result

The onSuccess callback is called when payment completes. Use it to redirect to a confirmation page or update your UI.
Always verify the payment on your backend via webhooks before fulfilling orders. The frontend callback is for UI purposes only.

Full Example

React SDK Reference

See all available props and customization options for KhaimeCheckout

Option 2: Redirect Checkout

If you don’t want to embed the checkout, redirect your customer to Khaime’s hosted checkout page.
The customer will complete payment on pay.khaime.com and be redirected back to your success_url when done.
For redirect checkout, make sure to set success_url and cancel_url in your API request so the customer returns to your site after payment.

Response Fields

Showing the fee to the customer

When fee_details.customer_pays_fees is true, the transaction fee is added to what the customer pays. If you render your own order summary, show fee_details.transaction_fee as a separate line before the customer pays, with fee_details.total_amount (equal to amount) as the total. It’s best practice for transparency — see Fees. When customer_pays_fees is false, the merchant absorbs the fee: show the product price as the total and no fee line.

Error Codes

Confirming Payment Status

Never trust frontend callbacks alone for order fulfillment. Always verify payments server-side.
Use webhooks to confirm payment outcomes:
  1. Listen for payment.succeeded and payment.failed events
  2. Verify the webhook signature
  3. Fulfill the order or handle the failure
After receiving a webhook, you can also use Get Transaction for on-demand status checks.

Notes

  • /payments/sessions and /payments/intents are aliases for the same endpoint.
  • This endpoint is for single-product purchases only. For multi-item carts (physical or digital), use Create Payment Intent.
  • For products outside Khaime’s catalog, use Create Charge instead.
  • Payment sessions expire after 30 minutes.
  • Always verify payments via webhooks before fulfilling orders.

Commerce Payment Intent

Multi-item cart checkout with shipping and digital products

Digital Cart Checkout

Guide for digital product multi-item carts