Groov Redirect Integration

What does the redirect integration look like?

👍

Eg: Integrating in your web portals (using Groov's redirect integration)

Rather than embedding a widget within your portal, this approach redirects the merchant to a Groov-hosted funding page (white-listed to your domian and brand as optional). Once the merchant completes or abandons the journey, Groov returns them to a URL of your choosing within your portal.

This integration requires no widget code, no token endpoint, and no server-to-server session handshake.

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 a single server-to-server call to Groov)
• You can identify merchants on your platform by a stable unique identifier (e.g. user ID, business ID, Merchant ID)

Eligibility check — should the CTA be shown?

Before surfacing the redirect CTA, your portal should confirm that Groov holds details for the given merchant. Make a server-side call to the Groov eligibility endpoint, passing the MerchantIdentifier for the logged-in merchant.

• Eligible — Groov has the merchant's details. Render the CTA.
• Not eligible — Either hide the CTA or render a passive "coming soon" state.

ℹ️

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 — Your server calls Groov to generate a redirect URL

When the merchant clicks the CTA, your server makes a GET request to the Groov redirect session endpoint:

GET https://app.wearegroov.io/api/v1/auth/consent/page
x-api-key: YOUR_GROOV_API_KEY
Content-Type: application/json

{
  "merchantIdentifier": "",
  "returnUrl": "https://yourportal.com/dashboard"
}

Parameters:

Groov returns a signed session redirectUrl.

Step 2 — Redirect the merchant

Return the redirectUrl to your portal frontend and redirect the merchant:

window.location.href = redirectUrl;

The merchant is taken to a Groov-hosted funding page styled with your bespoke branding (incl your custom domain setup). They complete or abandon the journey there.

Step 3 — Handle the return

On completion or abandonment, Groov redirects the merchant back to your returnUrl with a groov_status query parameter appended:

https://yourportal.com/dashboard?groov_status=completed
https://yourportal.com/dashboard?groov_status=abandoned

Read this on your return page to update the merchant's portal state accordingly:

const params = new URLSearchParams(window.location.search);
const status = params.get('groov_status');

if (status === 'completed') {
  // e.g. refresh dashboard, show confirmation
} else if (status === 'abandoned') {
  // e.g. log analytics, reset portal state
}

Limitations

This integration is intentionally simple. Before choosing it, note the following constraints:

ℹ️

If keeping the merchant within your portal experience is a priority, consider the Groov Web Embed integration instead.

Related

• x-api-keys
• Groov Eligibility API
• Domain Whitelisting
• Groov Web Embed Library — for a fully embedded widget experience
• Groov React Native Embed Library — equivalent guide for native mobile apps