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

# Components

> Reference for KhaimeCheckout and KhaimePaymentElement components

# Components

## KhaimeCheckout

The main checkout component with order summary and payment form.

```tsx theme={null}
import { KhaimeCheckout } from '@khaime/react';

<KhaimeCheckout
  token="eyJ..."
  onSuccess={(result) => console.log('Paid!', result)}
  onError={(error) => console.error(error)}
/>
```

### Props

<ParamField path="token" type="string" required>
  The payment token from your Khaime API. This is an opaque string - pass it directly without parsing.
</ParamField>

<ParamField path="productName" type="string">
  Override the product name shown in the order summary. If not provided, uses the name from the token.
</ParamField>

<ParamField path="productImage" type="string">
  Override the product image URL. If not provided, uses the image from the token.
</ParamField>

<ParamField path="showOrderSummary" type="boolean" default="true">
  Whether to show the order summary section above the payment form.
</ParamField>

<ParamField path="submitButtonText" type="string">
  Custom text for the submit button. Defaults to "Pay {amount}".
</ParamField>

<ParamField path="returnUrl" type="string">
  URL to redirect to after 3D Secure authentication (Stripe only). Defaults to current page.
</ParamField>

<ParamField path="onSuccess" type="(result: PaymentResult) => void">
  Called when payment is successful.
</ParamField>

<ParamField path="onError" type="(error: PaymentError) => void">
  Called when payment fails.
</ParamField>

<ParamField path="onReady" type="() => void">
  Called when the payment form is ready to accept input.
</ParamField>

<ParamField path="onClose" type="() => void">
  Called when user closes the payment popup (Paystack only).
</ParamField>

### Example with All Props

```tsx theme={null}
<KhaimeCheckout
  token={token}
  productName="Premium Plan"
  productImage="https://example.com/product.png"
  showOrderSummary={true}
  submitButtonText="Subscribe Now"
  returnUrl="https://myapp.com/checkout/complete"
  onSuccess={(result) => {
    console.log('Gateway used:', result.gateway);
    console.log('Payment ID:', result.paymentIntentId || result.reference);
    router.push('/success');
  }}
  onError={(error) => {
    toast.error(error.message);
  }}
  onReady={() => {
    console.log('Checkout ready');
  }}
  onClose={() => {
    console.log('User closed popup');
  }}
/>
```

***

## KhaimePaymentElement

A minimal payment form without the order summary. Use this when you want to build your own checkout UI.

```tsx theme={null}
import { KhaimePaymentElement } from '@khaime/react';

<KhaimePaymentElement
  token="eyJ..."
  onSuccess={(result) => console.log('Paid!')}
/>
```

### Props

<ParamField path="token" type="string" required>
  The payment token from your Khaime API.
</ParamField>

<ParamField path="returnUrl" type="string">
  URL to redirect to after 3D Secure authentication.
</ParamField>

<ParamField path="className" type="string">
  CSS class name to apply to the container.
</ParamField>

<ParamField path="onSuccess" type="(result: PaymentResult) => void">
  Called when payment is successful.
</ParamField>

<ParamField path="onError" type="(error: PaymentError) => void">
  Called when payment fails.
</ParamField>

<ParamField path="onReady" type="() => void">
  Called when the payment form is ready.
</ParamField>

<ParamField path="onClose" type="() => void">
  Called when user closes the popup (Paystack only).
</ParamField>

### Example: Custom Checkout Layout

```tsx theme={null}
function CustomCheckout({ token, product }) {
  return (
    <div className="checkout-container">
      {/* Your custom order summary */}
      <div className="order-summary">
        <img src={product.image} alt={product.name} />
        <h2>{product.name}</h2>
        <p className="price">${product.price}</p>
      </div>

      {/* Just the payment form */}
      <KhaimePaymentElement
        token={token}
        className="payment-form"
        onSuccess={(result) => {
          // Handle success
        }}
      />
    </div>
  );
}
```

***

## Types

### PaymentResult

Returned in the `onSuccess` callback.

```typescript theme={null}
interface PaymentResult {
  success: boolean;
  paymentIntentId?: string;  // Present for Stripe payments
  reference?: string;        // Present for Paystack payments
  gateway: 'stripe' | 'paystack' | 'startbutton';
}
```

### PaymentError

Returned in the `onError` callback.

```typescript theme={null}
interface PaymentError {
  code: string;
  message: string;
}
```

### Common Error Codes

| Code                  | Description                              |
| --------------------- | ---------------------------------------- |
| `card_declined`       | The card was declined                    |
| `insufficient_funds`  | Insufficient funds                       |
| `expired_card`        | The card has expired                     |
| `invalid_cvc`         | Invalid CVC code                         |
| `processing_error`    | Error processing the payment             |
| `missing_credentials` | Payment token is invalid or missing data |

***

## Styling

The components come with minimal default styling. You can customize the appearance:

### Using className

```tsx theme={null}
<KhaimePaymentElement
  token={token}
  className="my-payment-form"
/>
```

```css theme={null}
.my-payment-form button {
  background-color: #your-brand-color;
}
```

### Using Stripe Appearance API

For Stripe payments, you can customize the payment element appearance:

```tsx theme={null}
<KhaimeCheckout
  token={token}
  appearance={{
    theme: 'stripe',
    variables: {
      colorPrimary: '#0070f3',
      borderRadius: '8px',
    },
  }}
/>
```

<Note>
  The `appearance` prop only affects Stripe payments. Paystack uses its own popup styling.
</Note>