@ekko-earth/checkout-js

JavaScript SDK for Ekko Checkout integration.

Installation

npm install @ekko-earth/checkout-js

Usage

import { initCheckout } from '@ekko-earth/checkout-js';

const checkout = initCheckout({
  checkoutSessionId: 'cs_1234567890',
  clientSecret: 'sk_test_1234567890',
  mode: 'production',
  container: '#checkout-container', // or HTMLElement
  locale: 'en-GB',
  cspNonce: 'your-csp-nonce', // optional for CSP compliance
  features: {
    carbonCompensation: true,
    roundUp: true,
    rewardBar: true,
    learnMore: true
  },
  appearance: {
    theme: 'light',
    image: 'elephant',
    primaryColor: '#007bff',
    secondaryColor: '#6c757d',
    highlightColor: '#28a745',
    textFont: 'Inter, sans-serif',
    outerCornerRadius: 8
  },
  events: {
    ready: (event) => {
      console.log('Checkout ready!', event);
      console.log('Session ID:', event.checkoutSessionId);
      console.log('Carbon impact:', event.carbonImpact);
    },
    error: (event) => {
      console.error('Checkout error:', event);
      
      // Handle specific error codes as strings
      if (event.code === 'invalid_payment_method') {
        // Handle invalid payment method
      } else if (event.code === 'network_error') {
        // Handle network error  
      }
      // iframe can emit any error code - handle generically
    },
    toggleChanged: (event) => {
      console.log('Toggle changed:', event);
      console.log('Key:', event.key);
      console.log('Enabled:', event.enabled);
      console.log('Delta amount:', event.deltaAmount);
      console.log('Total payment:', event.totalPaymentAmount);
    },
    sizeChanged: (event) => {
      console.log('Size changed:', event);
      console.log('Height:', event.height);
      console.log('Width:', event.width);
    }
  }
});

// Cleanup when done
checkout.destroy();

API Reference

initCheckout(options)

Creates an embedded checkout instance.

Options

• checkoutSessionId (required): Your checkout session ID
• clientSecret (required): Client secret for authentication
• mode (required): Environment mode - one of:
  • 'production' - Production environment
  • 'sandbox' - Sandbox environment
• container (required): HTMLElement or CSS selector where to mount checkout
• locale (optional): Locale code (e.g., 'en-GB', 'fr-FR', 'de-DE', 'ar-SA')
• cspNonce (optional): CSP nonce for inline styles compliance
• features (optional): Feature toggles
  • carbonCompensation (boolean, default: true) - Show carbon compensation option
  • roundUp (boolean, default: true) - Show round up to donate option
  • rewardBar (boolean, default: true) - Show environmental impact rewards
  • learnMore (boolean, default: true) - Show learn more information
• appearance (optional): Visual customisation
  • theme: 'light' | 'dark' (default: 'light') - Overall colour scheme
  • image: 'elephant' | 'mountain' | 'forest' | 'ocean' (default: 'elephant') - Hero image
  • primaryColor (string) - Primary brand colour (hex)
  • secondaryColor (string) - Secondary colour (hex)
  • highlightColor (string) - Accent/highlight colour (hex)
  • textFont (string) - Font family for text
  • outerCornerRadius (number) - Border radius in pixels
• events (optional): Event callbacks

Event Types

ready(ReadyEvent) - Checkout is loaded and ready

• checkoutSessionId - Session ID
• carbonImpact.grams - Carbon impact in grams
• carbonImpact.ounces - Carbon impact in ounces
• carbonImpact.compensation.compensationValue - Compensation amount
• carbonImpact.compensation.serviceFee - Service fee
• carbonImpact.compensation.currencyCode - ISO 4217 currency code

error(ErrorEvent) - Error occurred

• code - Error code (string) - Can be any error code from iframe or SDK
• message - Human readable error message

Note: Error codes are not exported as enums since the iframe can emit any error code. Handle them as strings.

toggleChanged(ToggleChangedEvent) - User toggled a checkout option

• key - Toggle key: 'carbonCompensation' | 'roundUp'
• enabled - Whether toggle is now enabled
• deltaAmount - Amount change (minor units, positive/negative)
• totalContributionAmount - New total for this toggle
• totalPaymentAmount - New total payment amount
• currencyCode - ISO 4217 currency code

sizeChanged(SizeChangedEvent) - Checkout iframe size changed (optional)

• height - New height in pixels
• width - New width in pixels

Instance Methods

• destroy() - Remove checkout and cleanup resources