DocsSDK Quick Start

Quickstart in Minutes

Add ArosaPay's protected checkout to your e-commerce site with just a few lines of code.

3-minute integration

Built-in buyer protection

TypeScript support

Install the SDK

<!-- Add to your HTML <head> section -->
<script src="https://checkout.arosapay.com/v1/arosapay.js"></script>

<!-- Initialize with your API key -->
<script>
  ArosaPay.init({
    apiKey: 'pk_live_your_public_key',
    currency: 'KES',
    environment: 'production' // or 'sandbox' for testing
  });
</script>

HTML

Best for: Static sites, WordPress, simple integrations

Initialize with Your API Key

Need API keys? Create them in your Dashboard Settings → API Keys

// ES Module import
import { Arosapay } from '@arosapay/checkout';

// Initialize the SDK
const arosapay = new Arosapay({
  publicKey: 'pk_live_your_public_key',
  testMode: false,
  locale: 'en'
});

// Or use the static init method (same as CDN)
// ArosaPay.init({ apiKey: 'pk_live_xxx', environment: 'production' });

JavaScript

Create a Protected Transaction

// Create a protected transaction
const transaction = await ArosaPay.createTransaction({
  amount: 25000,
  title: 'iPhone 14 Pro Max',
  description: 'Brand new, sealed in box',
  vertical: 'electronics',
  satisfactionDays: 7,
  seller: {
    email: 'seller@example.com',
    name: 'John Doe',
    phone: '0712345678'
  }
});

console.log(transaction.paymentLink);
// https://app.arosapay.com/pay/abc123...

JavaScript

amount

Amount in KES (min 100)

vertical

electronics, fashion, motors, etc.

satisfactionDays

Buyer protection period (1-30)

Attach Checkout to Buttons

The easiest integration: add data attributes to your buy buttons and attach the checkout handler.

<!-- Add button with data attributes to your product page -->
<button 
  id="arosapay-checkout"
  data-amount="15000"
  data-product-name="Samsung Galaxy A54"
  data-product-description="128GB, Blue, Brand New"
  data-seller-email="shop@example.com"
  data-seller-name="Tech Electronics"
  data-delivery-days="3"
  data-vertical="electronics">
  Pay with ArosaPay (Protected)
</button>

<script>
  // Attach checkout to button - that's it!
  ArosaPay.attachCheckout('#arosapay-checkout');
  
  // Or with callback options:
  ArosaPay.attachCheckout('#arosapay-checkout', {
    theme: 'light',
    onSuccess: (result) => {
      console.log('Payment initiated!', result.reference);
      window.location.href = '/thank-you';
    },
    onError: (error) => {
      alert('Error: ' + error.message);
    }
  });
</script>

HTML

Supported Data Attributes

data-amount - Price in KES (required)

data-product-name - Product title (required)

data-product-description - Description

data-seller-email - Seller email

data-seller-name - Seller name

data-delivery-days - Expected delivery

data-satisfaction-days - Protection period (1-30)

data-vertical - electronics, fashion, motors, etc.

Multiple Buttons (Product Grid)

<!-- For product grids with multiple buy buttons -->
<div class="product-grid">
  <button class="buy-btn" data-amount="5000" data-product-name="Item 1">Buy</button>
  <button class="buy-btn" data-amount="7500" data-product-name="Item 2">Buy</button>
  <button class="buy-btn" data-amount="12000" data-product-name="Item 3">Buy</button>
</div>

<script>
  // Attach to all .buy-btn elements at once
  ArosaPay.attachCheckoutAll('.buy-btn', {
    seller: {
      email: 'shop@example.com',
      name: 'My Store'
    },
    defaultVertical: 'electronics',
    defaultSatisfactionDays: 7
  });
</script>

HTML

Open Checkout Programmatically (Advanced)

For more control, you can create transactions and open checkout modals programmatically.

// Open checkout modal for buyer to pay
await ArosaPay.checkout(transaction.id, {
  theme: 'light',
  branding: {
    primaryColor: '#0d9488',
    logo: 'https://yoursite.com/logo.png'
  },
  onSuccess: (result) => {
    console.log('Payment successful!', result.reference);
    // Redirect to success page
  },
  onError: (error) => {
    console.error('Payment failed:', error.message);
  },
  onClose: () => {
    console.log('Checkout closed');
  }
});

// Or create and checkout in one step:
await ArosaPay.checkoutWithNew({
  amount: 5000,
  title: 'Nike Air Max',
  seller: { email: 'shop@kicks.ke', name: 'Kicks Kenya' }
});

JavaScript

Handle Webhooks (Optional)

Receive real-time notifications when transaction status changes. Configure your webhook URL in the dashboard.

// Server-side webhook handler (Node.js example)
import { Arosapay } from '@arosapay/checkout';

app.post('/webhooks/arosapay', (req, res) => {
  const signature = req.headers['x-arosapay-signature'];
  const payload = JSON.stringify(req.body);
  
  // Verify webhook signature
  const isValid = Arosapay.verifyWebhook(
    payload, 
    signature, 
    process.env.AROSAPAY_WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const { event, data } = req.body;
  
  switch (event) {
    case 'transaction.paid':
      // Handle successful payment
      break;
    case 'transaction.completed':
      // Buyer confirmed satisfaction
      break;
    case 'transaction.disputed':
      // Handle dispute
      break;
  }
  
  res.status(200).send('OK');
});

JavaScript

Next Steps

API Reference

Complete documentation of all SDK methods and options.

View reference

Examples

Real-world integration examples and code samples.

View examples

Get API Keys

Generate your live and test API keys.

Go to settings