Merchant Integration Guide

Authorization: Bearer sp_live_YOUR_KEY

curl -X POST "https://seedhape.onrender.com/v1/orders" \
  -H "Authorization: Bearer sp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49900,
    "description": "Pro plan subscription",
    "externalOrderId": "your_order_123",
    "expectedSenderName": "Rahul Sharma",
    "expiresInMinutes": 15
  }'

{
  "id": "sp_ord_ab12cd34ef56",
  "amount": 49900,
  "originalAmount": 49900,
  "currency": "INR",
  "description": "Pro plan subscription",
  "status": "CREATED",
  "upiUri": "upi://pay?pa=merchant@ybl&pn=My+Store&am=499.00&tn=sp_ord_ab12cd34ef56&cu=INR",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...",
  "expiresAt": "2026-03-15T12:34:56.000Z",
  "createdAt": "2026-03-15T12:19:56.000Z"
}

curl "https://seedhape.onrender.com/v1/orders/sp_ord_ab12cd34ef56/status" \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

npm install @seedhape/sdk
# or
pnpm add @seedhape/sdk
yarn add @seedhape/sdk

// lib/seedhape.ts — server only, never import from the browser
import { SeedhaPe } from '@seedhape/sdk';

function getClient(): SeedhaPe {
  if (!process.env.SEEDHAPE_API_KEY) throw new Error('SEEDHAPE_API_KEY is not set');
  return new SeedhaPe({
    apiKey:  process.env.SEEDHAPE_API_KEY,
    baseUrl: process.env.SEEDHAPE_BASE_URL, // optional — omit for production default
  });
}

export async function createOrder(params: Parameters<SeedhaPe['createOrder']>[0]) {
  return getClient().createOrder(params);
}

export async function getOrderStatus(orderId: string) {
  return getClient().getOrderStatus(orderId);
}

import { createOrder } from '@/lib/seedhape';

const order = await createOrder({
  amount: 49900,               // required — amount in paise (₹499 = 49900)
  description: 'Pro plan',     // shown to the payer
  externalOrderId: 'ord_123',  // your own order ID for deduplication
  expectedSenderName: 'Rahul Sharma', // ⭐ strongly recommended — see Payment Matching
  customerEmail: 'rahul@example.com',
  customerPhone: '+919876543210',
  expiresInMinutes: 15,        // default: 30 minutes
  metadata: { userId: 'usr_abc', planKey: 'PRO' }, // any JSON, echoed in webhooks
});

console.log(order.id);      // "sp_ord_ab12cd34ef56"
console.log(order.upiUri);  // deep-link for UPI apps
console.log(order.qrCode);  // base64 PNG data URL

// Option A — redirect to seedhape-hosted payment page (easiest)
// Works for any framework (Next.js, Express, etc.)
const checkoutUrl = `https://yourdomain.com/pay/${order.id}`;
return redirect(checkoutUrl);

// Option B — browser SDK modal (single-page apps)
// order.id was created on your server (see Step 2 above) and passed to the client.
// showPayment only calls public /v1/pay/* endpoints — no API key is ever sent.
import { SeedhaPe } from '@seedhape/sdk';

const sp = new SeedhaPe({}); // no apiKey needed for showPayment

const result = await sp.showPayment({
  orderId: order.id,
  onSuccess: (result) => {
    console.log('Verified!', result.orderId, result.amount);
    // Webhook has already fired — just update your UI
  },
  onExpired: (orderId) => console.log('Expired:', orderId),
  onClose: () => console.log('User closed modal'),
});

// Poll status from your backend (server-side)
const status = await seedhape.getOrderStatus('sp_ord_ab12cd34ef56');
// { orderId, status, amount, verifiedAt? }

// OrderStatus values:
// CREATED | PENDING | VERIFIED | DISPUTED | RESOLVED | EXPIRED | REJECTED

npm install @seedhape/react @seedhape/sdk

// app/layout.tsx  (Next.js App Router — recommended)
import { SeedhaPeProvider } from '@seedhape/react';
import { SeedhaPe } from '@seedhape/sdk';
import type { CreateOrderOptions } from '@seedhape/sdk';

// Runs on the SERVER only — API key never reaches the browser.
async function createOrder(opts: CreateOrderOptions) {
  'use server';
  const client = new SeedhaPe({
    apiKey:  process.env.SEEDHAPE_API_KEY!,
    baseUrl: process.env.SEEDHAPE_BASE_URL,   // omit to use the default production URL
  });
  return client.createOrder(opts);
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SeedhaPeProvider onCreateOrder={createOrder}>
          {children}
        </SeedhaPeProvider>
      </body>
    </html>
  );
}

// src/main.tsx  (Vite / Create React App / any SPA)
// onCreateOrder proxies to your own backend — API key lives there, not here.
import { SeedhaPeProvider } from '@seedhape/react';
import type { CreateOrderOptions } from '@seedhape/sdk';

async function createOrder(opts: CreateOrderOptions) {
  const res = await fetch('/api/create-order', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(opts),
  });
  if (!res.ok) throw new Error('Order creation failed');
  return res.json();
}

export default function App() {
  return (
    <SeedhaPeProvider onCreateOrder={createOrder}>
      <Router />
    </SeedhaPeProvider>
  );
}

// ── Your backend (Express) ───────────────────────────────────────────────────
// import { SeedhaPe } from '@seedhape/sdk';
// const sp = new SeedhaPe({ apiKey: process.env.SEEDHAPE_API_KEY!, baseUrl: process.env.SEEDHAPE_BASE_URL });
// app.post('/api/create-order', express.json(), async (req, res) => {
//   const order = await sp.createOrder(req.body);
//   res.json(order);
// });

// app/root.tsx  (Remix)
import { SeedhaPeProvider } from '@seedhape/react';
import type { CreateOrderOptions } from '@seedhape/sdk';

async function createOrder(opts: CreateOrderOptions) {
  const res = await fetch('/api/create-order', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(opts),
  });
  if (!res.ok) throw new Error('Order creation failed');
  return res.json();
}

export default function App() {
  return (
    <html lang="en">
      <body>
        <SeedhaPeProvider onCreateOrder={createOrder}>
          <Outlet />
        </SeedhaPeProvider>
      </body>
    </html>
  );
}

// ── app/routes/api.create-order.ts ──────────────────────────────────────────
// import { json } from '@remix-run/node';
// import { SeedhaPe } from '@seedhape/sdk';
// const sp = new SeedhaPe({ apiKey: process.env.SEEDHAPE_API_KEY!, baseUrl: process.env.SEEDHAPE_BASE_URL });
// export async function action({ request }) {
//   const order = await sp.createOrder(await request.json());
//   return json(order);
// }

import { PaymentButton } from '@seedhape/react';

export default function CheckoutPage() {
  return (
    <PaymentButton
      amount={49900}                        // paise
      description="Pro subscription"
      expectedSenderName="Rahul Sharma"     // ⭐ recommended
      customerEmail="rahul@example.com"
      metadata={{ planKey: 'PRO' }}
      onSuccess={(result) => {
        console.log('Payment verified!', result);
        router.push('/dashboard?upgraded=true');
      }}
      onExpired={(orderId) => {
        console.log('Payment expired:', orderId);
      }}
      className="my-custom-btn-class"       // optional — disables default styles
    >
      Pay ₹499 →
    </PaymentButton>
  );
}

import { useState } from 'react';
import { PaymentModal } from '@seedhape/react';

export default function CustomCheckout({ orderId }: { orderId: string }) {
  const [open, setOpen] = useState(true);

  return (
    <PaymentModal
      orderId={orderId}
      open={open}
      onClose={() => setOpen(false)}
      onSuccess={(result) => {
        setOpen(false);
        // result.status is "VERIFIED" or "RESOLVED"
        console.log('Amount verified:', result.amount);
      }}
      onExpired={(id) => {
        setOpen(false);
        console.warn('Order expired:', id);
      }}
    />
  );
}

// app/api/checkout/route.ts  — server-side order creation
import { auth } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';
import { createOrder } from '@/lib/seedhape'; // your server utility

export async function POST(req: Request) {
  const { userId } = await auth();
  if (!userId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

  const { amount, description } = await req.json();

  const order = await createOrder({
    amount,
    description,
    externalOrderId: `${userId}_${Date.now()}`,
    metadata: { userId },
  });

  // Return order ID — client renders /pay/:orderId or opens modal
  return NextResponse.json({ orderId: order.id });
}

// order.verified — payment confirmed
{
  "event": "order.verified",
  "timestamp": "2026-03-15T11:11:11.000Z",
  "data": {
    "orderId": "sp_ord_ab12cd34ef56",
    "externalOrderId": "your_order_123",
    "amount": 49900,
    "originalAmount": 49900,
    "currency": "INR",
    "status": "VERIFIED",
    "utr": "426111234567",
    "senderName": "Rahul Sharma",
    "upiApp": "Google Pay",
    "verifiedAt": "2026-03-15T11:11:09.000Z",
    "metadata": { "userId": "usr_abc", "planKey": "PRO" }
  }
}

// app/api/webhooks/seedhape/route.ts  (Next.js App Router)
import crypto from 'node:crypto';

const WEBHOOK_SECRET = process.env.SEEDHAPE_WEBHOOK_SECRET!;

function verify(rawBody: string, signature: string): boolean {
  if (!signature.startsWith('sha256=')) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

export async function POST(req: Request) {
  const signature = req.headers.get('x-seedhape-signature') ?? '';
  const rawBody = await req.text();

  if (!verify(rawBody, signature)) {
    return new Response('Invalid signature', { status: 401 });
  }

  const payload = JSON.parse(rawBody);

  switch (payload.event) {
    case 'order.verified':
      await db.orders.update({
        where: { seedhapeOrderId: payload.data.orderId },
        data: { status: 'PAID', paidAt: payload.data.verifiedAt },
      });
      await fulfillOrder(payload.data.orderId);
      break;

    case 'order.expired':
      await db.orders.update({
        where: { seedhapeOrderId: payload.data.orderId },
        data: { status: 'EXPIRED' },
      });
      break;

    case 'order.disputed':
      await notifyMerchant('Payment needs manual review', payload.data.orderId);
      break;

    case 'order.resolved':
      await db.orders.update({
        where: { seedhapeOrderId: payload.data.orderId },
        data: { status: payload.data.status === 'RESOLVED' ? 'PAID' : 'REJECTED' },
      });
      break;
  }

  return new Response('OK', { status: 200 });
}

// Express / Hono / Fastify — same pattern, different syntax
import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use('/webhooks/seedhape', express.raw({ type: 'application/json' }));

app.post('/webhooks/seedhape', (req, res) => {
  const sig = req.headers['x-seedhape-signature'] as string;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.SEEDHAPE_WEBHOOK_SECRET!)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());
  // ... handle event
  res.sendStatus(200); // respond quickly, process async
});

// The matching engine uses expectedSenderName in TWO ways:
//
// 1. COLLISION RESOLVER — if multiple orders have the same amount in the 15-min
//    window, only the one whose expectedSenderName matches the notification
//    sender gets VERIFIED. Without a name, all colliding orders → DISPUTED.
//
// 2. FRAUD GUARD — even when matched via order ID in the transaction note,
//    if expectedSenderName is set and the actual sender doesn't match →
//    order is flagged as DISPUTED. Prevents someone else paying the same
//    amount to steal a verified order.
//
// Option A — merchant supplies name at order creation (recommended)
// The modal skips the name gate entirely.
const order = await seedhape.createOrder({
  amount: 49900,
  expectedSenderName: 'Rahul Sharma', // from your logged-in user profile
});

// Option B — customer enters name in the modal (no name known at creation)
// Don't pass expectedSenderName — the modal shows a name input step first,
// then calls POST /v1/pay/:orderId/expectation before showing the QR code.
const order = await seedhape.createOrder({
  amount: 49900,
  // no expectedSenderName → modal collects it from the customer
});

# POST /v1/pay/:orderId/expectation
# Public endpoint — no API key required
# Call this after creating the order, before the customer pays

curl -X POST "https://seedhape.onrender.com/v1/pay/sp_ord_ab12cd34ef56/expectation" \
  -H "Content-Type: application/json" \
  -d '{ "expectedSenderName": "Rahul Sharma" }'

# Response
{ "ok": true }

// If building a custom payment UI without the SDK/React package,
// call this endpoint after showing the name input to your customer.

const res = await fetch(`https://seedhape.onrender.com/v1/pay/${orderId}/expectation`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ expectedSenderName: customerName }),
});

if (!res.ok) throw new Error('Failed to set sender name');

# POST /v1/pay/:orderId/screenshot
# Public endpoint — no API key required
# Accepted when order status is PENDING, DISPUTED, or EXPIRED

curl -X POST "https://seedhape.onrender.com/v1/pay/sp_ord_ab12cd34ef56/screenshot" \
  -F "screenshot=@/path/to/payment-screenshot.jpg"

# Response
{
  "ok": true,
  "message": "Screenshot submitted for review",
  "screenshotUrl": "https://public.blob.vercel-storage.com/screenshots/sp_ord_ab12cd34ef56-..."
}

// Custom dispute UI — handle file input and upload directly
async function submitDispute(orderId: string, file: File) {
  const form = new FormData();
  form.append('screenshot', file);          // field name must be "screenshot"

  const res = await fetch(`https://seedhape.onrender.com/v1/pay/${orderId}/screenshot`, {
    method: 'POST',
    body: form,
    // Do NOT set Content-Type manually — browser sets multipart boundary automatically
  });

  if (!res.ok) throw new Error('Upload failed');
  const { screenshotUrl } = await res.json();
  return screenshotUrl; // public URL of the uploaded image
}

// When order.status === 'EXPIRED' or 'DISPUTED', the modal automatically
// shows a screenshot upload UI — no extra code needed on your end.
//
// The customer:
//  1. Sees "Link Expired" or "Under Review" in the modal
//  2. Uploads a screenshot of their UPI payment confirmation
//  3. Clicks "Submit Dispute"
//
// You receive an order.disputed webhook:
{
  "event": "order.disputed",
  "data": { "orderId": "sp_ord_ab12cd34ef56", "status": "DISPUTED" }
}
//
// After you review and resolve in the Android app or dashboard:
// → Approve  → order.resolved fires, status = "RESOLVED"
// → Reject   → order.resolved fires, status = "REJECTED"

case 'order.disputed':
  // Customer uploaded a screenshot — order needs manual review
  // Notify yourself (email, Slack, etc.) to check the Disputes tab
  await notifyTeam('Payment under review', payload.data.orderId);
  // Do NOT fulfill the order yet — wait for order.resolved
  break;

case 'order.resolved':
  if (payload.data.status === 'RESOLVED') {
    // You approved the dispute — fulfill the order
    await fulfillOrder(payload.data.orderId);
  } else {
    // You rejected it — inform the customer
    await markOrderRejected(payload.data.orderId);
  }
  break;