Introduction

Konbini Link

Konbini Link is an optional component of Konbini that lets you onboard users without having to worry about the specifics of their platform, or how it handles authentication. Instead, you can hand them off to Konbini Link, and if they finish the authentication flow successfully, you'll receive a token you can exchange for a merchant in Konbini.

In more practical terms, this means we provide you with a hosted onboarding UI that looks something like this:

A screenshot of the Konbini Link UI. The text reads: "You're connecting your store to Test App.. Select your platform to continue." Followed by a list of platforms: Shopify, Magento and WooCommerce.

There are two ways to use Konbini Link: the popup flow, which uses our JavaScript client library, and the redirect flow, which is more flexible and relies only on HTTP redirects. We'll go into each of these options below.


The popup flow relies on @usekonbini/link, a simple, lightweight JavaScript client library for Konbini Link. It lets you open the merchant authentication flow in a popup window, and calls a callback you define when the flow succeeds (or fails).

Here's how to use it:

Install the library using your package manager.

# npm
npm install @usekonbini/link

# yarn
yarn add @usekonbini/link

# pnpm
pnpm add @usekonbini/link

Alternatively, you can include the library using an HTML <script> tag and a CDN like UNPKG.

<script
  type="module"
  src="https://unpkg.com/@usekonbini/link@^1.0.1/dist/module.js"
/>

Import the KonbiniLink class. If you included the library using a <script> tag, you'll need to use the KonbiniLink global.

import { KonbiniLink } from '@usekonbini/link';
const KonbiniLink = window.KonbiniLink;

Initialize your KonbiniLink instance. The KonbiniLink constructor takes a configuration object with the following properties:

  • clientId - Your Konbini app's client ID.
  • onSuccess - A callback function that will be called with a claim token after a successful authentication flow.
  • onFailure - A callback function that will be called after an unsuccessful authentication flow.
const link = new KonbiniLink({
  clientId: `kbn_cid_your_client_id`,
  onSuccess: (token) => console.log(`Received a new claim token: ${token}`),
  onFailure: () => console.log(`Authentication flow failed.`),
});

Once you're ready to start the authentication flow, call the open() method.

link.open();

After you've received a claim token via the onSuccess callback, you'll need to pass it to the claimMerchant mutation to claim the new merchant and add it to your Konbini app. Make sure to do this server-side, not by making the API call from the browser and exposing your app's client secret!

Redirect flow

The redirect flow is more flexible, and allows you to use Konbini Link without relying on clientside JavaScript.

Redict URLs

Make sure your Konbini app has at least one redirect URL configured in the Konbini dashboard, or the redirect flow will fail.

Here's how to use it:

Send your user to the following URL.

https://merchants.usekonbini.com/start

This URL requires the following query parameters:

  • client_id: Your Konbini app's client ID.
  • redirect_to (optional): Your redirect URL. Must be one of the redirect URLs configured for your app in the Konbini dashboard. If left unset, your app's first redirect URL will be used.

Once the authentication flow has finished, the user will be sent back to your redirect URL.

If the authentication flow succeeded, the following query parameters will be added to the URL:

  • kbn_claim_token: A claim token that can be used with claimMerchant.

If the authentication failed, the following query parameters will be added to the URL:

  • kbn_auth_success: false

After you've received a claim token, you'll need to pass it to the claimMerchant mutation to claim the new merchant and add it to your Konbini app. Make sure to do this server-side, not by making the API call from the browser and exposing your app's client secret!

Previous
Terminology