Skip to main content

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.

​
Programmatic Checkout

When the price or product context needs to come from your backend — a custom quote, a WordPress shortcode, a dynamic subscription plan — create the checkout session on your server and hand the resulting session token to the SDK on the client. This is the flow used internally by the Khaime WordPress [khaime_checkout] shortcode.

​
1. Create the session on your server

Call the initialize endpoint with your secret API key. 
POST https://api.khaime.com/api/v1/sdk/checkout/initialize
X-Merchant-ID: YOUR_MERCHANT_ID
X-API-Key: sk_live_...
Content-Type: application/json

{
  "product_id": 789,
  "quantity": 1,
  "currency": "USD",
  "customer": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }
}
The response is a CheckoutSession: 
{
  "sessionToken": "khs_8f3a…",
  "amount": 5000,
  "currency": "USD",
  "productId": 789,
  "productTitle": "Premium Plan",
  "paymentGateway": "stripe",
  "expiresAt": "2026-04-18T00:00:00.000Z",
  "merchantBranding": { "name": "Acme", "logo": "...", "brandColor": "#42c3ff" }
}
The session token is single-use and short-lived. Generate it per customer, per transaction.

​
Example: PHP / WordPress

$response = wp_remote_post('https://api.khaime.com/api/v1/sdk/checkout/initialize', [
  'headers' => [
    'X-Merchant-ID' => '1234',
    'X-API-Key'     => 'sk_live_...',
    'Content-Type'  => 'application/json',
  ],
  'body' => json_encode([
    'product_id' => 789,
    'quantity'   => 1,
    'currency'   => 'USD',
    'customer'   => [
      'email'      => $user->user_email,
      'first_name' => $user->first_name,
      'last_name'  => $user->last_name,
    ],
  ]),
]);

$session = json_decode(wp_remote_retrieve_body($response), true);
$token   = $session['sessionToken'];

​
Example: Node.js

const res = await fetch('https://api.khaime.com/api/v1/sdk/checkout/initialize', {
  method: 'POST',
  headers: {
    'X-Merchant-ID': process.env.KHAIME_MERCHANT_ID,
    'X-API-Key': process.env.KHAIME_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product_id: 789,
    quantity: 1,
    currency: 'USD',
    customer: { email, first_name, last_name },
  }),
});

const { sessionToken } = await res.json();

​
2. Render the payment UI on the client

Pass the session token to sdk.createPayment(): 
<div id="khaime-checkout"></div>

<script src="https://api.khaime.com/sdk/v2/khaime.js"></script>
<script>
  const sdk = KhaimeSDK.init({ merchantId: '1234' });

  sdk.createPayment({
    sessionToken: 'khs_8f3a…', // passed in from your server
    container: '#khaime-checkout',
    onReady: () => console.log('Payment UI mounted'),
    onSuccess: ({ sessionToken, orderId, amount, currency, paymentMethod }) => {
      window.location.href = '/thank-you?order=' + orderId;
    },
    onError: (err) => {
      console.error('Payment failed:', err.message);
    },
  });
</script>
createPayment does three things:
  1. Fetches the session via GET /api/v1/sdk/checkout/session/{sessionToken} to retrieve gateway credentials.
  2. Lazy-loads the checkout modal component.
  3. Renders Stripe Elements or Paystack inline based on the session’s paymentGateway.
No API key is needed on the client — the session token is the authorization.

​
3. Confirm and fulfil

When the customer submits, the SDK calls POST /api/v1/sdk/checkout/session/{sessionToken}/confirm. On success, onSuccess fires with the order ID.
Always verify the order server-side via a webhook before fulfilling. The client callback only confirms the payment UI completed — webhooks confirm the charge.

​
When to use this flow

Use programmatic when…Use Pay Button when…
Price is computed server-side (quotes, upsells, coupons applied by your logic)Price comes from the product record in Khaime
You’re building inside WordPress, Drupal, or a CMS that renders HTML server-sideYou can drop a component on a static page
You want to pre-fill customer info from a logged-in sessionThe customer enters their own info
You need to create the session atomically with another backend action (e.g. reserve inventory)No atomicity required

​
Shortcut: server-side one-shot + redirect

If you don’t need an embedded UI, you can skip createPayment() entirely and redirect the customer to the Khaime-hosted checkout URL returned by the initialize endpoint. See the Create Session API reference.

​
Next steps