SplitPay SDK — v2.0.0

Split payments via UPI. No backend required.

An open-source SDK that lets your users split a completed payment with friends via UPI. All split data lives in the URL — no server, no database, no API keys.

Installation

Peer dependency: React 16.8+. The core export works without React.

Quick Start

Two components. That's the full integration.

1. Trigger — your checkout page

import { SplitPayTrigger } from 'splitpay-sdk'
import 'splitpay-sdk/css'

<SplitPayTrigger
  amount={1497}
  description="Swiggy Order #4821"
  merchantName="Swiggy"
  baseUrl="https://yourapp.com/pay"
/>

2. Recipient page — one route in your app

import { SplitPayRecipientPage } from 'splitpay-sdk'
import 'splitpay-sdk/css'

// Route: /pay — reads the URL hash automatically
<SplitPayRecipientPage />

SplitPayTrigger

The main entry point. Renders a "Split this payment" button and a self-contained modal with a 2-step flow: setup (UPI ID + headcount) and share (link + WhatsApp/native share).

SplitPayRecipientPage

The page recipients land on when they open the payment link. Reads split data from window.location.hash, shows the merchant context, amount breakdown, and per-app UPI pay buttons.

This component takes zero required props in production. Mount it on a /pay route and it handles everything.

Core Functions

For custom UIs, server-side link generation, or non-React apps. Zero dependencies.

import { encodeSplitUrl, decodeSplitUrl, splitAmount, generateUpiLink } from 'splitpay-sdk/core'

encodeSplitUrl(options)

Generates a payment link with all split data encoded in the hash fragment.

const link = encodeSplitUrl({
  baseUrl: 'https://yourapp.com/pay',
  upiId: 'xyz@upi',
  amount: 1497,
  count: 3,
  description: 'Dinner',
  initiatorName: 'Nikhil',
  merchantName: 'Swiggy',       // optional
  merchantLogo: 'https://...',   // optional
})

decodeSplitUrl(urlOrHash)

Decodes a payment link back into a split object.

const data = decodeSplitUrl(link)
// { upiId, perPersonAmount, totalAmount, count, description, initiatorName, merchantName, merchantLogo }

splitAmount(total, count)

Splits a total among N people. Remainder goes to the initiator.

splitAmount(1000, 3)
// { initiatorAmount: 334, recipientAmount: 333 }

generateUpiLink(options)

Generates a upi://pay?... deep link string.

generateUpiLink({ upiId: 'xyz@upi', amount: 499, description: 'Dinner' })
// "upi://pay?pa=xyz%40upi&am=499&tn=SplitPay+Dinner&cu=INR"

Theming

Pass a theme object to SplitPayTrigger. All values are optional.

<SplitPayTrigger
  theme={{
    primaryColor: '#e53935',
    primaryDeep: '#c62828',
    onPrimaryColor: '#ffffff',
    fontFamily: 'Your Font, sans-serif',
    borderRadius: '12px',
    modalWidth: '520px',
    triggerText: 'Split the bill',
  }}
  ...
/>

Link Format

The payment link encodes all split data in the URL hash fragment:

https://yourapp.com/pay#eyJ0IjoieHl6QHVwaSIsImEiOjQ5OSwiZCI6IkRpbm5lciIsImYiOiJOaWtoaWwi...}

The hash decodes to a compact JSON payload:

{
  "t": "xyz@upi",      // UPI ID (to)
  "a": 499,             // per-person amount
  "d": "Swiggy Order",  // description
  "f": "Nikhil",        // from (initiator name)
  "T": 1497,            // total amount
  "n": 3,               // split count
  "m": "Swiggy",        // merchant name (optional)
  "l": "https://..."    // merchant logo (optional)
}

UPI App Routing

On mobile, the recipient page shows per-app pay buttons using app-specific deep link schemes:

On desktop, a QR code is shown instead. The qrcode library is lazy-loaded via dynamic import.

Privacy

Everything after # in a URL is never sent over HTTP. This means:

• Your server never sees the UPI ID (even if you host the recipient page)
• CDN and proxy access logs don't contain it
• Analytics tools (Google Analytics, Mixpanel) don't capture it by default
• URL shorteners preserve hash fragments but don't log them server-side

The UPI ID only exists in two browsers: the initiator's (which generated the link) and the recipient's (which decoded it).

Status Tracking (Optional)

The default SDK is fully stateless — there's no server to tell you who paid. The initiator gets a UPI push notification when money arrives.

If you want an in-app "who paid?" panel, deploy the server template from server/ to your own Vercel + Upstash Redis:

This gives you SplitStatusPanel, useSplit, and useSplitStatus — the same components from v1, running on your own infrastructure.

SplitPay SDK — v1.1.0

Post-payment bill splitting for Indian merchants

A white-label React widget that lets your customers split a completed payment with friends via UPI — without you touching money, registering with a payment gateway, or building anything beyond a single component.

Installation

Install from npm:

npm install splitpay-sdk

Import the CSS once at your app's entry point. The SDK's styles are scoped with a .sp- prefix and won't conflict with your existing styles.

import 'splitpay-sdk/dist/splitpay.css'

Peer dependencies: React ≥ 16.8 and ReactDOM ≥ 16.8 must already be installed in your project. The SDK will not bundle its own copy of React.

Quick Start

Add one component to your payment confirmation page:

import { SplitPayTrigger } from 'splitpay-sdk'
import 'splitpay-sdk/dist/splitpay.css'

export function ConfirmationPage() {
  return (
    <div>
      <h1>Payment successful</h1>

      <SplitPayTrigger
        amount={12400}
        currency="INR"
        orderId="ORD-20489"
        description="Mumbai → Goa flight · IndiGo · 14 Jul"
        merchantName="SkyBook"
        onSplitCreated={(split) => console.log(split)}
      />
    </div>
  )
}

That is the complete merchant integration. The component handles the modal, the split link generation, and the Upstash KV persistence automatically.

Adding the recipient route

Mount SplitPayRecipientPage at /pay/:splitId and /pay/:splitId/:personSlug. The component is router-agnostic — pass IDs as props.

import { SplitPayRecipientPage } from 'splitpay-sdk'
import { useParams } from 'react-router-dom'

function PayRoute() {
  const { splitId, personSlug } = useParams()
  return <SplitPayRecipientPage splitId={splitId} personSlug={personSlug} />
}

SplitPayTrigger

The primary integration point. Renders a CTA card on your confirmation page. When clicked, opens a 3-step modal that guides the user through setting up the split.

SplitStatusPanel

Optional component for your order detail page. Polls the KV store every 5 seconds and shows who has confirmed payment.

import { SplitStatusPanel } from 'splitpay-sdk'

function OrderDetail({ orderId }) {
  return <SplitStatusPanel
    orderId={orderId}
    onResend={(memberId) => console.log('resend to', memberId)}
  />
}

SplitPayRecipientPage

The full recipient-facing page. Router-agnostic — mount it at /pay/:splitId/:personSlug (Variant B) and /pay/:splitId (Variant A) and pass the IDs as props.

Handles mobile and desktop automatically: on mobile it fires a upi:// deep link; on desktop it lazy-loads a QR code via import('qrcode') so the QR library is never sent to mobile clients.

Utility Functions

Imported from splitpay-sdk/utils. These wrap the KV API and can be used independently of the React components.

createSplit(config)

Creates a new split via POST /v1/splits. Stores the returned splitId in localStorage against orderId for SplitStatusPanel to find later.

const split = await createSplit({
  orderId:        'ORD-20489',
  totalAmount:    12400,
  currency:       'INR',
  description:    'Mumbai → Goa flight',
  initiatorUpiId: 'rahul@okicici',
  initiatorName:  'Rahul',
  members:        [{ name: 'Priya Sharma' }, { name: 'Sneha Kapoor' }],
  variant:        'unique',
})

getSplit(splitId)

Fetches a split from the KV store by ID. Used internally by SplitPayRecipientPage.

const split = await getSplit('sp_abc123')

getSplitByOrderId(orderId)

Resolves orderId → splitId via localStorage, then fetches from KV. Used by SplitStatusPanel.

const split = await getSplitByOrderId('ORD-20489')

confirmPayment(splitId, memberId?)

Self-confirms a payment via PATCH /v1/splits/:splitId/confirm. The call is idempotent — confirming twice returns the current state without error. For Variant A (shared link) splits, omit memberId — the server claims the first unpaid slot automatically.

// Variant B — unique link, memberId required
await confirmPayment('sp_abc123', 'm_001')

// Variant A — shared link, memberId omitted
await confirmPayment('sp_abc123')

generateUpiLink(config)

Builds a upi://pay deep link string. Transaction note is capped at 50 chars per UPI spec.

generateUpiLink({
  upiId:       'rahul@okicici',
  amount:      4133,
  description: 'Goa flight',
  currency:    'INR',
})
// → 'upi://pay?pa=rahul%40okicici&am=4133&tn=SplitPay+Goa+flight&cu=INR'

formatAmount(amount, currency)

formatAmount(4133, 'INR') // → '₹4,133'

Hooks

useSplit(splitId)

Fetches a split on mount and returns loading/error state.

const { split, loading, error, refetch } = useSplit(splitId)

useSplitStatus(orderId, options?)

Polls for split status on a configurable interval. Default interval is 5 seconds.

const { split, loading, error } = useSplitStatus(orderId, {
  pollInterval: 5000, // ms, default
})

Theming

Pass a theme object to SplitPayTrigger. The SDK injects CSS custom properties on :root so every component inherits the overrides.

<SplitPayTrigger
  theme={{
    primaryColor:   '#0052B4',  // IndiGo blue
    onPrimaryColor: '#ffffff',  // white text on dark button
    borderRadius:   '4px',
    brandName:      'IndiGo',
    logo:           '/indigo-logo.png',
  }}
  // ... other props
/>

Local Development

Running Locally

The project has two servers: the Vite dev server for the SDK demo, and the Express API server that proxies requests to Upstash Redis. You need both running simultaneously.

Terminal 1 — API backend

Terminal 2 — SDK demo (Vite)

Vite proxies all /v1/ requests to localhost:3001, so the browser never crosses origins. No CORS issues.

Smoke-testing the API

You can test the backend directly with curl:

Deploying the API

The backend is a standalone Vercel serverless project in the server/ directory. It targets api.splitpay.io as its production domain.

Environment Variables

SDK (root .env.local)

API backend (server/.env.local)

Amount Splitting Logic

Remainders from integer division stay with the initiator — the person who already paid. This ensures the split always sums exactly to the total with no floating-point leakage.

// ₹12,400 ÷ 3 people
splitAmount(12400, 3)
// → { initiatorAmount: 4134, recipientAmount: 4133 }
// 4134 + 4133 + 4133 = 12400 ✓

The modal shows this live as the user adjusts the count: "₹12,400 ÷ 3 people = ₹4,133 each. You already paid your share (₹4,134)."

UPI Deep Link Format

upi://pay?pa=rahul%40okicici&am=4133&tn=SplitPay+Goa+flight&cu=INR

On desktop, upi:// links don't open an app. The SDK detects non-mobile user agents and lazy-loads qrcode via import('qrcode'), rendering a 180×180px scannable QR. The QR library is never sent to mobile clients.