# Embedded Experiences

Some integrations require an embedded experience (e.g., a checkout/on-ramp/off-ramp flow inside your product).

Even if you call the APIs from your backend, you can present an embedded UI (hosted or iframe) to:

- collect beneficiary details
- confirm fees and totals
- handle compliance steps (KYC) when required


## Integration Options

### 1. JavaScript/TypeScript SDK

Install via npm:


```bash
npm install @kaito/checkout-sdk
```

**Basic usage:**


```typescript
import { KaitoCheckout } from '@kaito/checkout-sdk';

const checkout = new KaitoCheckout({
  partnerId: 'prt_abc123',
  environment: 'sandbox', // or 'production'
});

// On-ramp (FIAT -> CRYPTO)
checkout.onRamp({
  amount: 100,
  sourceCurrency: 'USD',
  destinationCurrency: 'USDT',
  destinationAddress: '0x...',
  onSuccess: (result) => console.log('Payment:', result.paymentId),
  onError: (error) => console.error(error),
  onCancel: () => console.log('User cancelled'),
});

// Off-ramp (CRYPTO -> FIAT)
checkout.offRamp({
  amount: 100,
  sourceCurrency: 'USDT',
  destinationCurrency: 'GTQ',
  beneficiary: {
    type: 'bank_account',
    bankCode: 'BANK_X',
    accountNumber: '1234567890',
  },
  onSuccess: (result) => console.log('Payout:', result.payoutId),
  onError: (error) => console.error(error),
});
```

**Available methods:**

- `onRamp(options)` — FIAT_CRYPTO flow
- `offRamp(options)` — CRYPTO_FIAT flow
- `transfer(options)` — CRYPTO_CRYPTO flow
- `payout(options)` — FIAT_FIAT flow


### 2. Hosted Checkout (Redirect)

For partners who prefer not to embed UI components, Kaito offers a hosted checkout page.

**Flow:**

1. Create a checkout session via API
2. Redirect user to `https://checkout.kai2.io/session/{sessionId}`
3. User completes the flow on Kaito's hosted page
4. User is redirected back to your `returnUrl`
5. Receive webhook confirmation



```bash
POST /checkout/sessions
{
  "railType": "FIAT_CRYPTO",
  "amount": 100,
  "currency": "USD",
  "returnUrl": "https://yourapp.com/checkout/complete",
  "cancelUrl": "https://yourapp.com/checkout/cancel",
  "metadata": { "orderId": "ORD-123" }
}
```

**Response:**


```json
{
  "sessionId": "ses_01JH...",
  "checkoutUrl": "https://checkout.kai2.io/session/ses_01JH...",
  "expiresAt": "2025-01-15T12:00:00Z"
}
```

### 3. iFrame Embed

Embed Kaito's checkout widget directly in your application.


```html
<iframe
  id="kaito-checkout"
  src="https://checkout.kai2.io/embed?partnerId=prt_abc123&sessionId=ses_01JH..."
  width="400"
  height="600"
  allow="payment"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
></iframe>

<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://checkout.kai2.io') return;
    
    const { type, data } = event.data;
    
    switch (type) {
      case 'kaito:checkout:success':
        console.log('Success:', data.paymentId || data.payoutId);
        break;
      case 'kaito:checkout:error':
        console.error('Error:', data.error);
        break;
      case 'kaito:checkout:cancel':
        console.log('Cancelled');
        break;
      case 'kaito:checkout:resize':
        document.getElementById('kaito-checkout').height = data.height;
        break;
    }
  });
</script>
```

**Sandbox attributes:**

- `allow-scripts` — Required for widget functionality
- `allow-same-origin` — Required for session management
- `allow-forms` — Required for input handling
- `allow-popups` — Required for 3DS/KYC redirects


### 4. Mobile SDKs (Coming Soon)

- **iOS**: `KaitoCheckoutSDK` via Swift Package Manager
- **Android**: `io.kai2:checkout-sdk` via Maven Central
- **React Native**: `@kaito/react-native-checkout`
- **Flutter**: `kaito_checkout`


## Customization

### Branding

Partners can customize the checkout experience via the Partner Portal:

- Logo
- Primary and secondary colors
- Font family
- Button styles


### Localization

Supported languages: `en`, `es`, `pt`

Pass `locale` parameter to override auto-detection:


```typescript
checkout.onRamp({
  locale: 'es',
  // ...
});
```

## Recommended Pattern (API + Embedded UI)

1. Create a quote (`POST /quotes`)
2. Optional: create execution plan (`POST /execution-plans`)
3. Execute (`POST /payments` or `POST /payouts`)
4. Listen for webhooks (`payment.*`, `payout.*`) to update UI and ledger


> If you later add a hosted/embedded UI, these same endpoints remain the backbone.


## Webhooks for Checkout Events

Subscribe to checkout-specific events:

- `checkout.session.created`
- `checkout.session.completed`
- `checkout.session.expired`
- `checkout.session.cancelled`