KonekButtonV1 Component

📝 Changelog

v3.44.0

Feature: Added buttonType prop for structured styling and buttonBorder option

v3.43.0

Feature: Added installation guide and url's to documentation

v3.42.0

Feature: Added comprehensive documentation with live demos and enhanced styling

v3.41.1-hotfix

Fix: Restored backwards compatibility for numeric values in sizing properties

v3.41.0

Feature: Implemented enhanced sizing system with support for multiple CSS units

📦 Installation

To use the KonekButtonV1 component in your project, include the SDK script in your HTML page's <head> section:

Environment URLs:

<script defer type="module" src="https://sdk.fit1.konek.dev/konek-sdk/konek-sdk.esm.js"></script>

<script defer type="module" src="https://sdk.konek.ca/konek-sdk/konek-sdk.esm.js"></script>

Complete HTML Example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My Konek Integration</title>
  
  <!-- Include Konek SDK (choose appropriate environment) -->
  <script defer type="module" src="https://sdk.konek.ca/konek-sdk/konek-sdk.esm.js"></script>
</head>
<body>
  <!-- Use the component anywhere in your page -->
  <konek-button-v1></konek-button-v1>
</body>
</html>

📋 Properties

🎯 Enhanced Unit Handling

Examples:

<konek-button-v1 height="48"></konek-button-v1>


<konek-button-v1 height="48px"></konek-button-v1>


<konek-button-v1 height="3em"></konek-button-v1>


<konek-button-v1 width="100%"></konek-button-v1>


<konek-button-v1 height="2.5rem"></konek-button-v1>

🎨 Button Type System

The component uses a structured buttonType system for consistent styling:

Button Types:

With Border Option:

⚡ Events

As a merchant integration, these are the events you should listen to on <konek-button-v1>: click, konekSuccess, konekError, and shippingOptions.

Event Reference

🌍 Locale Validation

The component validates the locales property and automatically defaults to 'en-CA' if an invalid locale is provided.

Supported locales:

• 'en-CA' (English - Canada)
• 'fr-CA' (French - Canada)

Invalid locales trigger an error log and reset to the default.

💻 Advanced Usage Examples

Basic Usage:

<!-- Basic usage -->
<konek-button-v1></konek-button-v1>

<!-- With custom properties -->
<konek-button-v1 
  locales="fr-CA"
  button-type="white-black"
  button-border="true"
  height="60px"
  width="200px"
  border-radius="8px"
  text-color="black-magenta">
</konek-button-v1>

<!-- With cart enabled -->
<konek-button-v1 
  show-cart="true"
  color="black" 
  height="48px">
</konek-button-v1>

Payment Flow Breakdown:

Event Handling Implementation:

const konekButton = document.querySelector('konek-button-v1') as KonekButtonElement;

// Handle button click - start payment flow
konekButton.addEventListener('click', async () => {
  if (!konekButton.client) {
    console.error('Konek client not available');
    return;
  }

  try {
    // Generate consent and show overlay
    const consent = // Create the Consent Data Object
    konekButton.client.addOverlay(); // Add the overlay

    // Submit consent to API
    const consentResponse = await fetch.post(`MARCHANT_BACKEND`, consent);
    konekButton.client.setConsentData(consentResponse.data); // Set consent data in the client
  } catch (error) {
    konekButton.client.setConsentError({
      error: 'createConsentFailed',
      details: error,
    });
    console.error('Consent error:', error);
  }
});

// Handle successful payment
konekButton.addEventListener('konekSuccess', async (event: Event) => {
  const customEvent = event as CustomEvent<string>;
  
  if (customEvent.detail === 'konekCompleted') {
    try {
      // Create checkout and redirect
      const checkoutData = {
        consentId: konekButton.client.consentId,
        correlationId: konekButton.client.correlationId,
      };

      const checkoutResponse = await axios.post(`MARCHANT_BACKEND`, checkoutData);
      window.location.href = `/orders/${checkoutResponse.data.orderId}`; // Redirect to order page
    } catch (error) {
      console.error('Checkout creation failed:', error);
    }
  }
});

// Handle payment errors
konekButton.addEventListener('konekError', (event: Event) => {
  const customEvent = event as CustomEvent<KonekErrorEventDetail>;
  console.error('Konek error:', customEvent.detail);

  if (konekButton.client) {
    konekButton.client.setConsentError({
      error: customEvent.detail?.error || 'konekErrorEvent',
      details: customEvent.detail,
    });
  }
});

konekv1.addEventListener('shippingOptions', event => {

    if(event.detail.type === "selectedOption") {
      
        // Update the Shipping Consent with the selected shipping option.

        // If just passing request_id with no data or error, it will be considered as consent update successful.
        const updateShippingConsentResponseSuccess = {
          request_id: event.detail.request_id,
        }
        
        // If just passing request_id with with error, it will be considered as consent update failed.
        const updateShippingConsentResponseFailure = {
          request_id: event.detail.request_id,
          error: {
            code: "Timeout",
            message:"The merchant failed to respond with the selected shipping option in time.",
            retry: true
          }
        }

        konekv1.client.updateShippingConsent(updateShippingConsentResponseSuccess);
    } else if(event.detail.type === "requestOptions") {

      // Generate shipping options to be presented to the user.
      
        // Response object when shipping options are successfully generated and returned to the user.
        const shippingOptionsResponse = {
            request_id: event.detail.request_id,
            data: [
            {
                shipping_option_id: crypto.randomUUID(),
                name: "Standard Delivery",
                description: "3–5 business days",
                shipping_cost: 0,
                category: "Delivery"
            },
            {
                shipping_option_id: crypto.randomUUID(),
                name: "Express Delivery",
                description: "1–2 business days",
                shipping_cost: 5,
                category: "Delivery"
            }
            ]
        }

        // Response object when there is an error generating or returning shipping options to the user.
        const shippingOptionsResponse = {
            request_id: event.detail.request_id,
            error: {
                code: "Timeout",
                message:"The merchant failed to respond with shipping options in time."
                retry: true
            }
        }
        konekv1.client.updateShippingOption(shippingOptionsResponse);

    }
})

🔧 Browser Compatibility

Built with Stencil, this component works in all modern browsers and can be used with any framework or vanilla JavaScript.