> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/hosted-checkout/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Hosted Checkout

> Learn how to integrate CrissCross's fully managed Hosted Checkout to provide a smooth and secure payment experience.

### Overview

CrissCross offers a **Hosted Checkout**, a fully managed front-end payment interface designed to handle the entire payment flow on behalf of merchants. It renders all available payment methods dynamically, manages necessary redirects and MFA challenges, and ensures PCI-compliant handling of sensitive data.

![](/_fern-files/crisscross.docs.buildwithfern.com/e58cb6165210d61e7f1ed10de7eaf9d04ba3f7805dba8c62706d6c6b9f53101f/docs/assets/hosted_checkout_all_methods.svg)

> **Optional Payment Initiation Flow**
>
> The Hosted Checkout is an optional payment initiation flow that manages all user engagement and interactions required by the relevant payment method. This approach is ideal for merchants seeking a streamlined, low-compliance solution.
>
> However, CrissCross also offers an alternative integration method:
>
> * **[Direct Integration](/direct-api-integration)**: Build your own checkout and call the API directly, for maximum flexibility and control over the payment process. Available for bank, mobile-money, and other non-card payment methods — card payments always run on Hosted Checkout.

---

### Key Features

1. **Dynamic Payment Method Rendering**:
   * Payment methods are rendered based on dynamic rules configured by the merchant. This process considers a broad set of variables, including those established during merchant configuration and those provided in the payment initiation call.
   * [Digital wallets](/payment-method-digital-wallets) are part of this: when Apple Pay or Google Pay is enabled on your account, the hosted checkout presents the wallet button automatically on devices and browsers that support it, with no wallet-specific integration work.

2. **3D Secure and MFA Support**:
   * Automatically handles multi-factor authentication (MFA) flows like 3D Secure, providing a secure checkout experience with minimal friction.

3. **PCI Compliance**:
   * Merchants avoid direct exposure to sensitive payment data, reducing the burden of PCI-DSS compliance.

4. **Customizable Checkout Experience**:
   * Merchants can customize the checkout to reflect their brand identity and align with their user experience (UX) preferences by adjusting colors and uploading their logo.

---

### How It Works

1. **Get an access token**
   * `POST /v1/auth/oauth2/token` with your `client_id` and `client_secret`. Tokens are valid for 24 hours — store one and reuse it rather than requesting a new one per call. See [Authentication](/authentication).

2. **Create a checkout session**
   * `POST /v1/checkout/session` with the amount, currency, your reference, and the payer's details. You get back a `sessionId` and a `paymentLink`. Keep both — the `sessionId` is how you match everything that follows back to this order, and the `paymentLink` is returned only in this response.

3. **Send the buyer to `paymentLink`**
   * Redirect them to the URL exactly as returned. It already carries the signature that authorises the session, so do not rebuild it by hand. CrissCross renders the available payment methods, collects the details, and handles any 3-D Secure or OTP step. A transaction (`transactionId`) is created the moment the buyer submits a payment method — not when the session is created or the link is opened. See [Payment Status & Recovery](/collect/payment-recovery) for how the two identifiers relate.

4. **Handle the return**
   * When the buyer finishes, they are sent to your `redirectUrl` with `?status=completed`, `?status=failed` or `?status=cancelled` appended. Treat this as a **display** signal only — show a confirmation or a retry page. It tells you the buyer came back, not that the money moved.

5. **Confirm with the webhook**
   * The webhook is the authoritative outcome. Each event carries the `transactionId`, the `sessionId`, and your `merchantReference` — match it to your order, verify its signature, and only then fulfil. A buyer who closes the tab still produces a webhook; a buyer who returns with `?status=completed` may still be pending. See [Webhook Events](/webhook-events).

> **Note**
>
> Steps 4 and 5 are easy to conflate. The redirect is what the *buyer* did; the webhook is what *happened to the payment*. Fulfil on the webhook.

#### Example Checkout Session Request:

```bash
curl --request POST 'https://api.crisscross.money/v1/checkout/session' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "merchantId": "YOUR_MERCHANT_ID",
    "merchantReference": "ORDER_12345",
    "amount": 5000,
    "currency": "ZAR",
    "integrationType": "hosted",
    "redirectUrl": "https://merchant-site.com/redirect",
    "payerDetails": {
      "emailAddress": "customer@example.com",
      "location": "ZAF",
      "fullName": "John Doe"
    },
    "paymentAttributes": {
      "orderId": "ORDER_12345"
    }
  }'
```

#### Example Response:

```json
{
  "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
  "paymentLink": "https://checkout.payos.money/session/0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a?signature=kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM",
  "payerId": "2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f",
  "signature": "kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM"
}
```

The `payerId` is a persistent identifier for the customer behind this session. Store it against your customer record — you can pass it back on future sessions to recognise a returning customer. See [Payer ID](/payer-id) for details.

The `signature` authorises this session on the hosted checkout page. It is already appended to `paymentLink`, so redirect the buyer to that URL exactly as returned and you never need to touch the field itself. Anyone holding it can act on the session, so keep it out of logs and analytics. It is not related to the `svix-signature` header used to verify [webhooks](/core-concepts-webhooks) — different mechanism, different purpose.

> **Pricing in one currency, collecting in another?**
>
> [Adaptive Currency Conversion](/adaptive-currency-conversion) charges the payer in their own currency while you price in yours. The conversion is priced one of two ways: by a per-session rate minted automatically at creation (the default — nothing to set), or by a [rate lock](/rate-locks) you fetched ahead of time and pass as `rateLockId` — the same locked rate then holds across every session you attach it to. With a rate lock, the create response also returns `fxCommit` with the amount the payer will be charged; with the per-session rate, the response above returns identifiers only — read the session back and inspect `fxCommit`.

---

### Handling Webhooks

CrissCross sends webhooks for key events, so merchants can update order statuses in real time. For a hosted checkout session, the two you'll act on most are:

* **`transaction.completed`**: Update order status to 'Paid' and proceed with fulfillment.
* **`transaction.failed`**: Notify the customer and allow them to retry.

See [Webhook Events](/webhook-events) for the full event catalogue and payload schemas, and [Webhooks](/core-concepts-webhooks) for signature verification and delivery.

The delivered body is the transaction itself, with no envelope around it — match each event to your order on the top-level `sessionId` or `merchantReference`, and verify its signature before acting on it.

---

### Customizing the Checkout Experience

Merchants can configure the following elements:

* **Logo**: Upload your logo to personalize the checkout page.
* **Theme**: Adjust colors to match your brand identity.
* **Payment Method Order**: Control the order in which payment methods appear.

---

### FX Rate Display (Adaptive Currency Conversion)

When a session initiates in one currency and collects in another, [Adaptive Currency Conversion](/adaptive-currency-conversion) converts for the payer, and the hosted page shows both the original charge and the converted amount they'll actually be debited. The conversion is priced either by a per-session rate minted at creation (the default; refreshes on the page automatically if it expires mid-checkout) or by a [rate lock](/rate-locks) passed as `rateLockId` (frozen for the lock's lifetime — no refresh).

Merchants can toggle each element of the buyer-facing breakdown via `paymentAttributes` on the session. All three toggles default to shown — set to `"false"` to hide.

| Attribute            | Default  | Purpose                                                                                                                    |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `showChargedAs`      | `"true"` | Show the original merchant-priced amount (in the initiation currency) alongside the converted amount the payer is debited. |
| `showConversionRate` | `"true"` | Show the effective all-in rate the conversion was applied at.                                                              |
| `showConversionFee`  | `"true"` | Show the conversion fee, derived from the merchant's configured markup.                                                    |

All `paymentAttributes` values are strings. To hide an element, pass `"false"`; anything else (or omitting the key) leaves it visible.

The fee percentage shown reflects the per-currency-pair markup configured on the merchant's account before they start transacting. Use these `paymentAttributes` to shape what the payer sees on the checkout page.

---

### Benefits of Using Hosted Checkout

* **Faster Go-to-Market**: Launch in days, not months, with a pre-built, compliant checkout that works across all local payment methods.
* **Fully Customizable**: Match your brand with your logo, colors, and design to increase trust, while we handle the infrastructure and compliance.
* **Higher Conversion**: Optimized user flows and localized payment options help boost completion rates by **over 10% on average** across markets.
* **Reduced Compliance Burden**: CrissCross handles sensitive data securely, reducing PCI compliance requirements for merchants.
* **Seamless Customer Experience**: A smooth payment journey with automatic handling of redirects and authentication.
* **Rapid Integration**: The Hosted Checkout can be integrated with minimal development effort.

---

### Example Integration Flow

```mermaid
sequenceDiagram
    participant Merchant as Merchant
    participant CrissCross as CrissCross
    participant User as Customer

    Merchant->>CrissCross: Create checkout session
    CrissCross->>Merchant: Returns checkout URL
    Merchant->>User: Redirect to Hosted Checkout
    User->>CrissCross: Completes payment on Hosted Checkout
    CrissCross->>Merchant: Sends payment status via webhook
```

---

### Conclusion

The CrissCross Hosted Checkout offers a comprehensive solution for managing payments with minimal effort. It provides dynamic payment method support, automatic handling of MFA flows, and reduces compliance burden. Merchants can focus on their core business while CrissCross ensures a smooth and secure payment process.

> Seamlessly manage your checkout with CrissCross