Skip to content
/
Embedded Experiences
Last updated

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:

npm install @kaito/checkout-sdk

Basic usage:

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

{
  "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.

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

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
Previous page
Next page