Groov Web Embed Library

What does integrating Groov widgets look like?

👍

Eg: Integrating in web portals/browser based applications (using Groov's Web Embed library)

The following steps explain the setup and handshake between your web portal and Groov's platform, enabling a seamless funding (e.g: MCA) journey embedded directly within your merchants' authenticated portal session.

⚠️

This page is Work in Progress

Before you begin

Prerequisites

• Your organisation has a Groov account and has been issued an x_api_key
• You have access to your backend server (to make server-to-server calls to Groov)
• You can identify merchants on your platform by a stable unique identifier (e.g. user ID, business ID, Merchant ID)

Integration model

Groov's web embed renders as a contained widget within your existing portal page. You choose how it surfaces to your merchants:

ℹ️

All three modes use the same underlying integration steps. The choice only affects how you render the widget container in your frontend.

Eligibility check — should the CTA be shown?

ℹ️

This section is only applicable to either Option A or Option B as detailed in 1.Integration Steps below.

Before rendering the widget, your portal should determine whether Groov already holds details for a given merchant. This prevents the CTA from appearing for merchants Groov cannot yet service.

Make a server-side call to the Groov eligibility endpoint, passing the MerchantIdentifier (a stable unique identifier (e.g. user ID, business ID, Merchant ID)) for the logged-in merchant. Groov will return an eligibility status.

• Eligible — Groov has the merchant's details. Render the CTA and proceed with the integration steps below.
• Not eligible — Groov does not have this merchant's details. Either hide the CTA or render a passive "coming soon" state — your preference.

ℹ️

The eligibility check should happen server-side on page load. Do not expose your x_api_key to the browser.

Refer to Groov Eligibility API for endpoint details.

Integration steps

Step 1 — Implement the widget/mode to your portal frontend

Choose your integration mode

Option A — JS SDK / Web Component

Install Groov's web embed library:

npm install @wearegroov/web-embed --save

Import and mount the widget in your portal frontend:

import { GroovWidget } from '@wearegroov/web-embed';

<GroovWidget
  tokenEndpoint="/api/groov/token"   // Your server endpoint — see Step 2
  containerId="groov-funding-widget"
  theme={optionalThemeConfig}        // Optional — Groov default styling applied if omitted
  onEvent={handleGroovEvent}         // Optional — see Event handling below
/>

The widget calls tokenEndpoint on initialisation to fetch the gWidgetId. Steps 2–4 remain the same.

ℹ️

tokenEndpoint should be a route on your server — not a direct call to Groov. The widget calls this endpoint to fetch the gWidgetId on initialisation. This keeps your x_api_key server-side only.

ℹ️

Requires a React-compatible frontend. For non-React stacks, use Option B.

Option B — iFrame embed

Place a Groov-hosted iFrame in your portal layout:

<iframe
  id="groov-widget-frame"
  src="about:blank"
  width="100%"
  height="700"
  frameborder="0"
  allow="payment"
></iframe>

Once your server has completed the Steps 2–3 handshake and returned the gWidgetId, set the iFrame src to activate the widget:

const frame = document.getElementById('groov-widget-frame');
frame.src = `https://app.wearegroov.io/api/v1/embed?gWidgetId=${gWidgetId}`;

To receive journey events from the widget, listen for postMessage:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.wearegroov.io/api') return;
  handleGroovEvent(event.data);
});

⚠️

You must whitelist https://app.wearegroov.io/api in your Content Security Policy frame-src directive, and validate event.origin on every postMessage received. See Domain Whitelisting for setup.

⚠️

The exact URLs used for example app.wearegroov.io are illustrative conventions and will be confirmed later

Step 2 — Implement a token endpoint on your server

Your server needs a new endpoint (e.g. POST /api/groov/token) that:

1. Receives a request from the authenticated portal frontend
2. Reads the logged-in merchant's identifier from your session/auth context
3. Makes a server-to-server POST request to Groov (Step 3)
4. Returns the gWidgetId to the frontend

This step is a communication between your portal client and your portal server. The URL of this endpoint is passed to the widget in Step 1.

Step 3 — Your server calls Groov to register the session

From your server endpoint, make a POST request to the Groov widget session endpoint:

POST https://api.wearegroov.io/v1/widget/session
x-api-key: YOUR_GROOV_API_KEY
Content-Type: application/json

{
  "gWidgetId": "<token generated by Groov widget on init>",
  "merchantIdentifier": "<your stable merchant ID>"
}

Parameters:

Groov returns a confirmation, after which the widget will activate using the bound gWidgetId.

Step 4 — The widget runs the funding journey

Once Groov has received the gWidgetId, the widget initialises the merchant's funding journey within your portal. The journey appears as part of your application — styled to your theme — making the process feel fully embedded.

From this point, all product interaction within the widget is controlled by Groov, with direct communication between the Groov widget and Groov's app server.

ℹ️

Any new portal session (e.g. after logout and re-login, or session timeout) will regenerate a new gWidgetId via the handshake in Steps 2–3. The merchantIdentifier remains constant and Groov will always restore the merchant's contextual state.

Event handling

Unlike a native mobile context, your web portal may need to react to journey events — for example, refreshing a dashboard after funding completes, or logging an abandoned session.

Pass an onEvent handler to the widget:

function handleGroovEvent(event) {
  switch (event.type) {
    case 'JOURNEY_COMPLETED':
      // e.g. refresh merchant dashboard, show confirmation UI
      break;
    case 'JOURNEY_ABANDONED':
      // e.g. log analytics, reset portal state
      break;
    case 'JOURNEY_ERROR':
      // e.g. surface an error state to the merchant
      break;
  }
}

Refer to Groov Widget Events for the full event schema.

Theming and white-labelling

Groov applies default styling out of the box. To match your portal's brand, pass an optional theme config:

const themeConfig = {
  primaryColor: '#0057FF',
  fontFamily: 'Inter, sans-serif',
  borderRadius: '8px',
};

<GroovWidget theme={themeConfig} ... />

Refer to Groov Widget Theming for the full token reference.

Security requirements

⚠️

These requirements protect your merchants and your organisation. Non-compliance may cause widget initialisation to fail.

• Never expose x_api_key in frontend code. All Groov API calls must originate from your server.
• Only serve the token endpoint to authenticated users. Gate POST /api/groov/token behind your existing session/auth middleware.
• Configure Content Security Policy (CSP) headers to allow Groov's widget origin:

  frame-src https://*.wearegroov.io;
  connect-src https://api.wearegroov.io;

• Cross-origin communication between the widget and your portal uses postMessage. Groov restricts this to whitelisted origins registered against your organisation account. Ensure your portal domain is registered — refer to Domain Whitelisting.

Browser compatibility

The Groov web embed library supports all modern browsers:

📘

Internet Explorer support is TBC. Microsoft officially retired and ended support for IE11. Because it no longer receives crucial security updates, using it leaves users computer highly vulnerable to malware and hackers.

Sequence diagram

Portal Browser          Portal Server           Groov Server
      |                       |                       |
      |  Page load (merchant  |                       |
      |  authenticated)       |                       |
      |──────────────────────►|                       |
      |                       |  Check eligibility    |
      |                       |──────────────────────►|
      |                       |◄──────────────────────|
      |◄──────────────────────|  Render CTA if eligible
      |                       |                       |
      |  Merchant clicks CTA  |                       |
      |  Widget initialises,  |                       |
      |  requests gWidgetId   |                       |
      |──────────────────────►|                       |
      |                       |  POST /widget/session |
      |                       |  {gWidgetId,          |
      |                       |   merchantIdentifier} |
      |                       |──────────────────────►|
      |                       |◄──────────────────────|
      |◄──────────────────────|  Return gWidgetId     |
      |                       |                       |
      |  Widget activates,    |                       |
      |  journey begins       |◄─────────────────────►|
      |  (Groov ↔ Groov       |                       |
      |   direct comms)       |                       |

Related

• x-api-keys
• Groov Eligibility API
• Groov Widget Events
• Groov Widget Theming
• Domain Whitelisting
• Groov React Native Embed Library — equivalent guide for native mobile apps