# Integrate Kismet Checkout

> Integrate Kismet Checkout with your own payment processor or Stripe, and connect agent-led direct bookings through Agent Pay.


Use the SDK to build your catalog, search, stay selection, and guest account.
Then hand the selected stay to **Kismet Checkout**. Bring your own payment
processor or run on Stripe. Kismet Checkout is designed to work with **Agent Pay**,
which lets agents book directly with managers.

A checkout Fixture embeds Kismet Checkout in a partner experience. A qualified
partner booking engine can also retain its own checkout when it meets the
channel's requirements. Keeping an existing processor or engine is an integration
choice to review with Kismet, not a browser-selected payment route.

## Choose your integration

| What you need | Supported path | What it does not imply |
| --- | --- | --- |
| A branded catalog and stay picker | SDK catalog, search, and availability reads | Display estimates are not final checkout offers. |
| Checkout on a configured site | Kismet Checkout through a supported [Fixture installation](https://developers.kismet.travel/fixtures.md) or the configured hosted destination | A manifest or SDK installation does not activate commerce. |
| Your preferred payment processor | Bring your own processor through a supported integration, or run Kismet Checkout on Stripe | Processor setup is separate from installing the SDK or Fixture. |
| Agent-led direct bookings | Kismet Checkout is designed to work with Agent Pay so agents can book directly with managers | The collection's booking and payment integration must be configured; guest sign-in or a saved card alone does not authorize a booking. |
| Your existing booking engine or checkout | A reviewed partner integration that satisfies the channel's handoff and outcome requirements | There is no self-service, arbitrary-engine checkout API in the current Developer API. |
| A sandbox booking-request test | [`createVacationRentalBookingRequest`](https://developers.kismet.travel/api/reference/create-vacation-rental-booking-request.md) with a TEST installation | It cannot charge or create a production reservation. LIVE returns `SANDBOX_ONLY`. |

Commerce availability depends on the collection, the selected integration,
supported payment methods, and installation target. Contact
[engineering@makekismet.com](mailto:engineering@makekismet.com?subject=Kismet%20Checkout%20integration)
to configure or verify those requirements. The SDK does not provide a universal
LIVE `book()` or `pay()` operation.

## Carry the selected stay to your configured route

The SDK's `configured-checkout` recipe covers public stay intent: property slug,
check-in, check-out, and guest count. The URL helper is available from the
`@kismet-tech/sdk/contracts` entry point in the current source candidate. Check
your [installed SDK artifact](https://developers.kismet.travel/guides/private-evaluation.md) before using it.

```ts
import {
  buildConfiguredCheckoutUrl,
  parseConfiguredCheckoutUrl,
} from '@kismet-tech/sdk/contracts';

// Your app owns this route and has configured its checkout integration.
// This is not an assumed route on the Kismet-hosted checkout service.
const checkoutOrigin = 'https://staging.example.com';
const checkoutPath = '/checkout';
const checkoutUrl = buildConfiguredCheckoutUrl({
  origin: checkoutOrigin,
  checkoutPath,
  property: 'fern-ridge-cabin',
  checkIn: '2027-01-11',
  checkOut: '2027-01-16',
  guests: 4,
});

// Validate again at your receiving route before invoking its integration.
const incomingUrl = new URL(checkoutUrl);
if (incomingUrl.origin !== checkoutOrigin) throw new Error('Unexpected checkout origin');
const intent = parseConfiguredCheckoutUrl(incomingUrl, { checkoutPath });
if (!intent.valid || !intent.selection) throw new Error('Invalid stay selection');
const selectedStay = intent.selection;
```

Render `checkoutUrl` as the destination of your checkout link. Keep the origin and
path in trusted deployment configuration, never in a visitor-controlled redirect
parameter. The helper validates URL shape and stay fields; it does not verify
domain registration, collection scope, inventory, or checkout readiness.
It currently accepts property slugs and 1–16 guests, not arbitrary product types.

This URL is **not a quote, booking, payment authorization, or guest session**.
Do not add prices, API keys, guest tokens, payment credentials, or a
`confirmed=true` flag. The receiving integration obtains a current authoritative
offer and the guest agrees to its price and terms before booking. If Kismet or a
partner returns a prepared checkout URL, use it as returned; do not reconstruct
it with this helper or append private session material.

Keep staging destinations on staging. A staging hostname does not make a LIVE
installation or payment route safe for testing; select the explicitly configured
test path as well.

## Embed or open Kismet Checkout

Use the installation instructions for the enabled Fixture target. For example,
the WordPress checkout panel has the existing `kismet/checkout-panel` block and
`[kismet_checkout_panel]` shortcode. These identifiers remain unchanged.
The [Fixture catalog](https://developers.kismet.travel/fixtures.md#the-catalog) describes installation support;
do not assume a React export or generic iframe mount exists because a WordPress
block does.

The host may customize supported theme tokens and the surrounding page.
Payment-instrument capture remains in the integration's trusted-origin frame;
do not collect card details in your components or copy checkout internals into
your site. The checkout integration owns the authoritative offer, payment route,
reservation submission, and confirmation.

## Retain a partner checkout

A partner checkout must be reviewed for the intended channel. The integration
needs to preserve the selected inventory, dates and guests, exchange identity
through an approved mechanism, support the channel's required payment methods,
and report the reservation outcome back to Kismet.

The partner handoff and confirmation contract is not yet a published, general
Developer API operation. Agree the supported destination, authentication,
test environment, callback/reconciliation mechanism, and fallback behavior with
Kismet before enabling it. Do not invent a callback URL or send a guest bearer
token in a query string.

When a partner engine cannot meet the channel requirements, Kismet Checkout can
be the configured fallback. Do not switch engines automatically after an
ambiguous payment or reservation timeout: reconcile the original attempt first.

## Show truthful outcomes

- **Changed price or terms:** present the new offer for agreement; never submit
  a total copied from a search card or URL.
- **Unavailable stay:** keep the visitor's selection visible and let them change
  it. Do not silently book another property.
- **Pending or unknown:** show that confirmation is pending. A successful
  redirect, closed drawer, or client event is not proof of a reservation.
- **Confirmed:** use the integration's authoritative reservation result. Payment
  success alone is not proof that inventory was booked. Keep payment status and
  reservation status distinct.
- **Retry:** follow the integration's reconciliation and idempotency contract;
  do not start a second payment or booking because a browser request timed out.

## Test the handoff before enabling commerce

Exercise the same selection from a results card and a property-detail page.
Both must reach the same configured destination with identical stay fields.
Also check malformed dates, invalid guest counts, unavailable inventory, changed
prices, reloads, and a missing checkout integration. Never substitute fixture
prices when a real authority is unavailable.

For a site that declares the existing `configured-checkout` recipe:

```sh
npx kismet recipes explain --recipe configured-checkout
npx kismet recipes test --recipe configured-checkout --url http://127.0.0.1:3000
```

Passing that recipe proves the stay-intent and re-quote behavior, **not** payment
processing or production booking readiness. Complete the selected integration's
TEST flow and server-confirmed outcome checks separately before any authorized
LIVE pilot. See [recipes and implementation tests](https://developers.kismet.travel/sdk/recipes.md) and
[platform status](https://developers.kismet.travel/guides/platform-status.md).