API Options

When creating a payment intent with the Khaime API, you can configure how the response is returned.

Default Behavior (Token)

By default, the API returns a token - an opaque string that the React SDK decodes internally.

// Request
const response = await fetch('https://api.khaime.com/v1/payment/intent', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${KHAIME_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 4400,
    currency: 'USD',
    customer_email: 'customer@example.com',
  }),
});

// Response
{
  "ok": true,
  "data": {
    "reference": "PAY_abc123",
    "token": "eyJpbnRlbnRfaWQiOiJpbnRlbnRfYzhlYzU5..."
  }
}

Use this token with @khaime/react:

<KhaimeCheckout token={data.token} />

Redirect URL Mode

If you want a redirect URL instead of embedding the checkout, pass returnType: "url":

// Request
const response = await fetch('https://api.khaime.com/v1/payment/intent', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${KHAIME_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 4400,
    currency: 'USD',
    customer_email: 'customer@example.com',
    return_type: 'url',  // Request a redirect URL
  }),
});

// Response
{
  "ok": true,
  "data": {
    "reference": "PAY_abc123",
    "redirectUrl": "https://pay.khaime.com/checkout?ref=abc123"
  }
}

Then simply redirect your user:

window.location.href = data.redirectUrl;

Some payment gateways (like Startbutton) only support redirect URLs. In these cases, the API automatically returns redirectUrl regardless of your return_type setting.

When to Use Each Mode

Mode	Use Case
Token (default)	Embedded checkout in your app, best UX
URL	Redirect to hosted checkout page, simplest integration

Token Mode Benefits

Seamless checkout experience
Customer stays on your site
Full control over UI

URL Mode Benefits

No frontend code needed
Works with any platform
Hosted by Khaime (PCI compliant)

Gateway-Specific Behavior

Different gateways render differently:

Gateway	Token Mode	URL Mode
Stripe	Embedded payment form	Redirect to Khaime hosted checkout
Paystack	Opens popup	Opens popup
Startbutton	Shows redirect button	Direct redirect

Startbutton doesn’t support embedded forms. The component will show a “Continue to Payment” button that redirects the user.

Example: Handling Both Modes

function CheckoutPage({ checkoutData }) {
  // If we got a redirect URL, redirect immediately
  if (checkoutData.redirectUrl) {
    useEffect(() => {
      window.location.href = checkoutData.redirectUrl;
    }, []);
    return <div>Redirecting to payment...</div>;
  }

  // Otherwise, render the embedded checkout
  return (
    <KhaimeCheckout
      token={checkoutData.token}
      onSuccess={(result) => {
        window.location.href = '/success';
      }}
    />
  );
}

​API Options

​Default Behavior (Token)

​Redirect URL Mode

​When to Use Each Mode

​Token Mode Benefits

​URL Mode Benefits

​Gateway-Specific Behavior

​Example: Handling Both Modes

API Options

Default Behavior (Token)

Redirect URL Mode

When to Use Each Mode

Token Mode Benefits

URL Mode Benefits

Gateway-Specific Behavior

Example: Handling Both Modes