> ## 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.

# API Options

> Configure how the Khaime API returns payment data

# 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.

```typescript theme={null}
// 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`:

```tsx theme={null}
<KhaimeCheckout token={data.token} />
```

## Redirect URL Mode

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

```typescript theme={null}
// 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:

```typescript theme={null}
window.location.href = data.redirectUrl;
```

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

## 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                    |

<Warning>
  Startbutton doesn't support embedded forms. The component will show a "Continue to Payment" button that redirects the user.
</Warning>

## Example: Handling Both Modes

```tsx theme={null}
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';
      }}
    />
  );
}
```