Sika SDK

Embed Sika checkout directly on your website with a beautiful modal. No redirects required.

Features

• Embedded Checkout - Keep customers on your site with a modal checkout
• No Redirects - Better conversion rates with seamless payment experience
• Mobile Optimized - Responsive design that works on all devices
• Event Callbacks - Handle success, cancel, and error events
• TypeScript Support - Full type definitions included

Installation

CDN (Recommended for quick start)

<script src="https://js.withsika.com/v1/sika.js"></script>

npm

npm install @withsika/sdk

yarn

yarn add @withsika/sdk

Quick Start

1. Create a checkout on your server

First, create a checkout session on your server using the Sika API:

// Server-side (Node.js example)
const response = await fetch('https://api.withsika.com/checkout/initialize', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${SIKA_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    amount: 10000, // GHS 100.00 in pesewas
    description: 'Order #123',
  }),
});

const { reference } = await response.json();
// Return `reference` to your frontend

2. Open checkout on your frontend

<button id="pay-button">Pay Now</button>

<script src="https://js.withsika.com/v1/sika.js"></script>
<script>
  const sika = new Sika('sika_test_pk_your_public_key');

  document.getElementById('pay-button').addEventListener('click', async () => {
    // Get reference from your server
    const response = await fetch('/api/create-checkout', { method: 'POST' });
    const { reference } = await response.json();

    // Open checkout modal
    sika.checkout({
      reference: reference,
      onSuccess: (result) => {
        console.log('Payment successful!', result.reference);
        // Redirect to success page or update UI
        window.location.href = '/order-complete';
      },
      onCancel: () => {
        console.log('Payment cancelled');
      },
      onError: (error) => {
        console.error('Payment failed:', error.message);
      },
    });
  });
</script>

Framework Examples

React

import { useCallback } from 'react';

// Load SDK via script tag in index.html or use useEffect to load dynamically

function CheckoutButton({ amount, email }) {
  const handleCheckout = useCallback(async () => {
    // Create checkout on your server
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ amount, email }),
    });
    const { reference } = await response.json();

    // Open Sika checkout modal
    const sika = new window.Sika('sika_test_pk_xxx');
    sika.checkout({
      reference,
      onSuccess: (result) => {
        // Handle success - clear cart, show confirmation, etc.
        console.log('Payment successful!', result.reference);
      },
      onCancel: () => {
        console.log('Payment cancelled');
      },
      onError: (error) => {
        console.error('Payment failed:', error.message);
      },
    });
  }, [amount, email]);

  return (
    <button onClick={handleCheckout}>
      Pay Now
    </button>
  );
}

Next.js

'use client';

import Script from 'next/script';
import { useState } from 'react';

declare global {
  interface Window {
    Sika: new (publicKey: string) => {
      checkout: (options: {
        reference: string;
        onSuccess?: (result: { reference: string }) => void;
        onCancel?: () => void;
        onError?: (error: { message: string }) => void;
      }) => void;
    };
  }
}

export default function CheckoutPage() {
  const [sdkReady, setSdkReady] = useState(false);

  const handleCheckout = async () => {
    const response = await fetch('/api/checkout', { method: 'POST' });
    const { reference } = await response.json();

    const sika = new window.Sika('sika_test_pk_xxx');
    sika.checkout({
      reference,
      onSuccess: (result) => {
        window.location.href = `/success?ref=${result.reference}`;
      },
      onCancel: () => {
        console.log('Cancelled');
      },
    });
  };

  return (
    <>
      <Script
        src="https://js.withsika.com/v1/sika.js"
        onLoad={() => setSdkReady(true)}
      />
      <button onClick={handleCheckout} disabled={!sdkReady}>
        Pay with Sika
      </button>
    </>
  );
}

Vue.js

<template>
  <button @click="handleCheckout" :disabled="!sdkLoaded">
    Pay Now
  </button>
</template>

<script setup>
import { ref, onMounted } from 'vue';

const sdkLoaded = ref(false);

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://js.withsika.com/v1/sika.js';
  script.onload = () => { sdkLoaded.value = true; };
  document.head.appendChild(script);
});

const handleCheckout = async () => {
  const response = await fetch('/api/checkout', { method: 'POST' });
  const { reference } = await response.json();

  const sika = new window.Sika('sika_test_pk_xxx');
  sika.checkout({
    reference,
    onSuccess: (result) => {
      console.log('Success!', result.reference);
    },
    onCancel: () => {
      console.log('Cancelled');
    },
  });
};
</script>

ES Modules

import { Sika } from '@withsika/sdk';

const sika = new Sika('sika_test_pk_your_public_key');

sika.checkout({
  reference: 'checkout_reference_from_server',
  onSuccess: (result) => {
    console.log('Payment successful!', result.reference);
  },
  onCancel: () => {
    console.log('Payment cancelled');
  },
  onError: (error) => {
    console.error('Payment failed:', error.message);
  },
});

API Reference

new Sika(publicKey, config?)

Creates a new Sika SDK instance.

| Parameter | Type | Description | |-----------|------|-------------| | publicKey | string | Your Sika public key (starts with sika_test_pk_ or sika_live_pk_) | | config.checkoutUrl | string | (Optional) Custom checkout URL. Defaults to https://pay.withsika.com |

sika.checkout(options)

Opens the checkout modal.

| Option | Type | Description | |--------|------|-------------| | reference | string | Required. Checkout reference from /checkout/initialize | | onSuccess | function | Called when payment succeeds. Receives { reference, status } | | onCancel | function | Called when user closes the modal without paying | | onError | function | Called when payment fails. Receives { reference, status, message } | | onLoad | function | Called when the checkout iframe has loaded |

sika.close()

Programmatically closes the checkout modal.

// Example: Close after timeout
const sika = new Sika('sika_test_pk_xxx');

sika.checkout({
  reference: 'abc123',
  onLoad: () => {
    // Auto-close after 5 minutes of inactivity
    setTimeout(() => sika.close(), 5 * 60 * 1000);
  },
});

TypeScript Support

The SDK includes TypeScript definitions:

import { Sika, CheckoutOptions, CheckoutSuccessResult, CheckoutErrorResult } from '@withsika/sdk';

const sika = new Sika('sika_test_pk_xxx');

const options: CheckoutOptions = {
  reference: 'abc123',
  onSuccess: (result: CheckoutSuccessResult) => {
    console.log('Reference:', result.reference);
    console.log('Status:', result.status); // 'succeeded'
  },
  onError: (error: CheckoutErrorResult) => {
    console.error('Error:', error.message);
  },
};

sika.checkout(options);

Redirect vs Embedded Checkout

| Feature | Redirect | Embedded (SDK) | |---------|----------|----------------| | User stays on your site | No | Yes | | Implementation complexity | Simple | Simple | | Customization | Limited | Callbacks for full control | | Mobile experience | Good | Excellent (slides up) | | Conversion rate | Good | Better |

When to use Redirect

• Simple integration with minimal code
• When you don't need real-time payment feedback
• Server-side rendered applications

When to use Embedded (SDK)

• Better user experience with no page reload
• Real-time feedback on payment status
• Single-page applications (React, Vue, etc.)
• Higher conversion rates

Browser Support

The SDK supports all modern browsers:

• Chrome (last 2 versions)
• Firefox (last 2 versions)
• Safari (last 2 versions)
• Edge (last 2 versions)

Troubleshooting

Modal doesn't open

Make sure the SDK is loaded before calling checkout():

// Wait for SDK to load
if (typeof window.Sika === 'undefined') {
  console.error('Sika SDK not loaded');
  return;
}

CORS errors

The checkout reference must be created on your server using your secret key. Never expose your secret key in frontend code.

Payment callbacks not firing

Ensure your checkout reference is valid and not expired. Checkout references expire after 30 minutes.

Security

• Never expose your secret API key in frontend code
• Always create checkout sessions on your server
• Verify payment status on your server before fulfilling orders
• Use webhook notifications for reliable payment confirmation

Support

• Documentation: https://docs.withsika.com
• Email: [email protected]
• GitHub Issues: https://github.com/withsika/sdk/issues

License

MIT