docs.checkout

Checkout widget

DigiPin-powered smart address checkout for Indian e-commerce. Two-step flow: map pin → auto-filled form. One package for React web, iOS, and Android.

Live demo

What it does

The checkout widget replaces broken Indian address forms with a precise pin-drop flow. Buyers drag a map pin, see their DigiPin offline in real time (~4 m precision), then confirm auto-filled state, district, locality, and pincode before entering flat and building details.

Platform	Bundler	Map engine	Install extras
React / Next.js / Vite / Nuxt	Webpack / Vite	MapLibre GL JS	`maplibre-gl`
iOS (Expo / React Native)	Metro	expo-osm-sdk	`expo-osm-sdk expo-location`
Android (Expo / React Native)	Metro	expo-osm-sdk	`expo-osm-sdk expo-location`

Same import on all platforms — Metro resolves .native.tsx files on mobile; Vite and Webpack use the web components.

Quick start (web)

Get an API key — sign up at developers.quantaroute.com and create a project.
Install the package and MapLibre:

bash

npm install @quantaroute/checkout maplibre-gl

Import CSS in your app entry or root layout, then render the widget:

tsx

import 'maplibre-gl/dist/maplibre-gl.css';
import '@quantaroute/checkout/style.css';
import { CheckoutWidget } from '@quantaroute/checkout';

export default function CheckoutPage() {
  return (
    <CheckoutWidget
      apiKey={process.env.NEXT_PUBLIC_QUANTAROUTE_KEY!}
      onComplete={(address) => {
        console.log(address.digipin);           // "39J-438-TJC7"
        console.log(address.pincode);           // "110011"
        console.log(address.formattedAddress);  // "Flat 4B, Floor 3rd, ..."
      }}
    />
  );
}

Next.js (App Router)

MapLibre requires the browser — load the widget with dynamic(..., { ssr: false }). Import both stylesheets in app/layout.tsx.

tsx

// app/checkout/page.tsx
'use client';

import dynamic from 'next/dynamic';

const CheckoutWidget = dynamic(
  () => import('@quantaroute/checkout').then((m) => m.CheckoutWidget),
  { ssr: false }
);

export default function CheckoutPage() {
  return (
    <CheckoutWidget
      apiKey={process.env.NEXT_PUBLIC_QUANTAROUTE_KEY!}
      onComplete={(addr) => console.log(addr)}
    />
  );
}

Native (Expo)

Requires a development build — does not work in Expo Go because expo-osm-sdk uses native modules.

bash

npm install @quantaroute/checkout expo-osm-sdk expo-location

# Add @quantaroute/checkout/plugin to app.json, then rebuild:
npx expo run:ios
npx expo run:android

Use the same CheckoutWidget import — no CSS import on native; styles are React Native StyleSheet objects.

Props reference

Core props

Prop	Type	Default	Description
`apiKey`req	string	—	QuantaRoute API key from the developer portal.
`onComplete`req	(addr: CompleteAddress) => void	—	Called when the buyer submits a complete delivery address.
`apiBaseUrl`	string	https://api.quantaroute.com	Override the geocoding API base URL.
`onError`	(err: Error) => void	—	Called when the widget encounters an unrecoverable error.
`defaultLat / defaultLng`	number	India center	Initial map center before the user drops a pin.
`theme`	'light' \| 'dark'	light	Color scheme for the widget UI.
`mapHeight`	string \| number	380px / 380	Map height — string on web (e.g. 380px), number on native.
`title`	string	Add Delivery Address	Heading shown at the top of the widget.
`enableSearch`	boolean	true	Show unified search bar for address autocomplete and offline DigiPin decode.
`brandColor`	string (hex)	#0ea5e9	Accent color for buttons, map pin, and highlights.
`logoUrl`	string (URL)	—	Brand logo displayed in the widget header.
`onCheckoutEvent`	(event: CheckoutEvent) => void	—	Fires on every step transition — forward to MoEngage, GTM, or your analytics backend.

Phone & email OTP auth

Enable saved addresses and buyer sessions. Set up a merchant account via merchant onboarding to get your merchantId and Edge Function URL.

Prop	Type	Default	Description
`enablePhoneAuth`	boolean	false	Start with phone OTP. Requires merchantId and supabaseFunctionBaseUrl.
`enableEmailAuth`	boolean	false	Start with email OTP via Resend. Phone auth takes precedence if both are set.
`merchantId`	string	—	Merchant UUID from checkout onboarding.
`supabaseFunctionBaseUrl`	string	—	Base URL for checkout Edge Functions, e.g. https://<project>.supabase.co/functions/v1

tsx

<CheckoutWidget
  apiKey={process.env.NEXT_PUBLIC_QUANTAROUTE_KEY!}
  merchantId={process.env.NEXT_PUBLIC_MERCHANT_ID!}
  supabaseFunctionBaseUrl={process.env.NEXT_PUBLIC_SUPABASE_FUNCTION_URL!}
  enableEmailAuth={true}
  enableSearch={true}
  onComplete={(addr) => console.log(addr)}
  onCheckoutEvent={(event) => console.log('[checkout]', event.type, event)}
/>

CompleteAddress output

The onComplete callback receives a structured address object ready for your backend or payment gateway:

typescript

interface CompleteAddress {
  digipin: string;          // "39J-438-TJC7"
  lat: number;              // 28.61390
  lng: number;              // 77.20900

  // Auto-filled from QuantaRoute API
  state: string;            // "Delhi"
  district: string;         // "New Delhi"
  division: string;         // "New Delhi Central"
  locality: string;         // "Nirman Bhawan SO"
  pincode: string;          // "110011"
  delivery: string;         // "Delivery" | "Non Delivery"
  country: string;          // "India"

  // Manual entry by user
  flatNumber: string;       // "4B"
  floorNumber: string;      // "3rd"
  buildingName: string;     // "Sunshine Apartments"
  streetName: string;       // "MG Road, Action Area"

  formattedAddress: string; // "4B, 3rd Floor, Sunshine Apartments, ..."
}

Checkout events

Use onCheckoutEvent to track funnel steps without server-side integration:

Event	When fired
`phone_step_viewed`	Phone entry screen rendered
`otp_sent`	SMS OTP dispatched via MSG91
`phone_verified`	SMS OTP correct; session created
`email_step_viewed`	Email input screen rendered
`email_otp_sent`	OTP dispatched via Resend
`email_verified`	Email OTP correct; session created
`map_step_viewed`	Map pin step rendered
`location_confirmed`	Buyer tapped Confirm location
`form_step_viewed`	Address detail form rendered
`address_completed`	Full address submitted

Advanced: sub-components

Compose your own two-step flow with exported building blocks:

tsx

import {
  MapPinSelector,
  AddressForm,
  getDigiPin,
  isWithinIndia
} from '@quantaroute/checkout';

// Offline DigiPin — no API call
const dp = getDigiPin(28.6139, 77.2090); // "39J-438-TJC7"

Merchant admin API

Server-side REST API for checkout analytics, configuration, and webhook management. Authenticate with x-api-key (your merchant api_key from this portal).

Base URL: https://{project_ref}.supabase.co/functions/v1. Replace with your project ref from merchant onboarding.

GET/checkout-admin?action=funnelx-api-key

Query checkout data

Fetch funnel metrics, sessions, webhook deliveries, COD config, or webhook settings.

query parameters

Name	Required	Description
`action`	Yes	One of: funnel, sessions, webhook_deliveries, cod_config, webhooks
`from`	No	Start datetime (ISO 8601).
`to`	No	End datetime (ISO 8601).
`limit`	No	Page size (default 50).
`offset`	No	Pagination offset (default 0).

PATCH/checkout-admin?action=cod_configx-api-key

Update checkout config

Update COD eligibility or webhook settings.

query parameters

Name	Required	Description
`action`	Yes	cod_config or webhooks

request

json

{
  "enable_cod": true,
  "cod_max_cart_value_paise": 500000,
  "cod_blocked_pincodes": ["110001"]
}

POST/checkout-admin?action=test_webhookx-api-key

Test webhook delivery

Queue a test webhook delivery to verify your endpoint and HMAC signature handling.

query parameters

Name	Required	Description
`action`	Yes	test_webhook

POST/checkout-funnel-events

Log funnel event

Log a checkout funnel step event from a custom integration. No authentication required.

request

json

{
  "merchant_id": "your-merchant-uuid",
  "event_type": "address_completed",
  "step": "form",
  "device_type": "mobile",
  "platform": "web"
}

POST/checkout-paymentx-api-key

Payment actions

Create Razorpay orders, verify payments, or record COD orders. Requires x-session-token header from an authenticated checkout session.

request

json

{
  "action": "create_order",
  "amount_paise": 49900
}

GET/checkout-offersx-api-key

UTM offer banner

Return a UTM-matched offer banner for the current checkout session. Requires x-session-token header.

POST/checkout-offersx-api-key

Manage UTM offers (admin)

List or create UTM-matched promotional offers.

request

json

{
  "action": "create",
  "utm_source": "instagram",
  "banner_text": "Free shipping today"
}

Environment variables

Variable	Description
`NEXT_PUBLIC_QUANTAROUTE_KEY`	Geocoding API key for address search and reverse geocoding.
`NEXT_PUBLIC_MERCHANT_ID`	Merchant UUID — required for OTP auth and saved addresses.
`NEXT_PUBLIC_SUPABASE_FUNCTION_URL`	Checkout Edge Functions base URL.

Ready to integrate?

Run merchant onboarding to get your snippet with all values pre-filled.

Start merchant setup