Get started with upiagent

npm install upiagent

import { UpiAgent } from "upiagent/client";

const upi = new UpiAgent({ apiKey: process.env.UPIAGENT_API_KEY });

// 1. Create payment — returns a QR code
const payment = await upi.createPayment({
  amount: 499,
  note: "Order #123",
  addPaisa: true,  // ₹499 → ₹499.37 (unique amount for matching)
});

// 2. Show QR to customer
// payment.qrDataUrl  → base64 PNG for <img src={...} />
// payment.intentUrl  → upi://pay?... for mobile deep link

// 3. Verify — checks your Gmail for bank alert automatically
const result = await upi.verify(payment.id);

if (result.verified) {
  console.log("Paid!", result.payment.senderName, result.payment.upiReferenceId);
}

import { UpiAgent } from "upiagent/client";

const upi = new UpiAgent({ apiKey: process.env.UPIAGENT_API_KEY });

const payment = await upi.createAndWaitForPayment(
  { amount: 499, note: "Order #123", addPaisa: true },
  {
    onPaymentCreated: (p) => {
      // Show QR to customer
      console.log("Scan to pay:", p.qrDataUrl);
    },
    onStatusUpdate: (p) => {
      console.log("Status:", p.status);
    },
    pollInterval: 5000,   // check every 5s
    timeout: 180_000,     // give up after 3 min
  }
);

if (payment.status === "verified") {
  console.log("Payment confirmed!", payment.senderName);
}
// "expired" | "cancelled" → final, show a retry button

// app/api/pay/route.ts
import { UpiAgent } from "upiagent/client";

const upi = new UpiAgent({ apiKey: process.env.UPIAGENT_API_KEY! });

export async function POST(req: Request) {
  const { amount, orderId } = await req.json();

  const payment = await upi.createPayment({
    amount,
    note: `Order ${orderId}`,
    addPaisa: true,
  });

  return Response.json({
    id: payment.id,
    qrDataUrl: payment.qrDataUrl,
    intentUrl: payment.intentUrl,
    amount: payment.amount,
  });
}

// app/api/pay/[id]/route.ts
export async function GET(
  _req: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const status = await upi.getStatus(id);
  return Response.json(status);
}

"use client";
import { useState } from "react";

// Your webhook handler marks the order paid. The page checks once when the
// customer says they've paid — no polling.
export function Checkout({ amount }: { amount: number }) {
  const [payment, setPayment] = useState<any>(null);
  const [status, setStatus] = useState("idle");

  async function pay() {
    const res = await fetch("/api/pay", {
      method: "POST",
      body: JSON.stringify({ amount, orderId: "ORD_123" }),
    });
    setPayment(await res.json());
    setStatus("pending");
  }

  async function check() {
    const r = await fetch(`/api/pay/${payment.id}`);
    setStatus((await r.json()).status); // claimed = screenshot OK, verified = bank-confirmed
  }

  if (status === "idle") return <button onClick={pay}>Pay ₹{amount}</button>;
  if (status === "pending") return (
    <div>
      <img src={payment.qrDataUrl} alt="Scan to pay" />
      <a href={payment.intentUrl}>Open UPI App</a>
      <button onClick={check}>I've paid</button>
    </div>
  );
  if (status === "claimed") return <p>Received — confirming with the bank… <button onClick={check}>Refresh</button></p>;
  if (status === "verified") return <p>Payment confirmed!</p>;
  return <p>Payment {status}. Try again.</p>;
}

import express from "express";
import { UpiAgent } from "upiagent/client";

const app = express();
app.use(express.json());

const upi = new UpiAgent({ apiKey: process.env.UPIAGENT_API_KEY! });

app.post("/pay", async (req, res) => {
  const payment = await upi.createPayment({
    amount: req.body.amount,
    note: req.body.note,
    addPaisa: true,
  });
  res.json(payment);
});

app.get("/pay/:id", async (req, res) => {
  const status = await upi.getStatus(req.params.id);
  res.json(status);
});

app.post("/pay/:id/verify", async (req, res) => {
  const result = await upi.verify(req.params.id);
  res.json(result);
});

app.listen(3000);

const result = await upi.verify(payment.id);

// result.verified    → true if payment matched
// result.payment     → { amount, upiReferenceId, senderName, bankName, confidence }
// result.status      → "pending" | "claimed" | "verified" | "expired" | "cancelled"
// result.message     → failure reason if not verified

const proof = await upi.submitProof(payment.id, {
  image: screenshotBase64,   // or "data:image/png;base64,..."
  mediaType: "image/png",
});

// proof.accepted    → true if the screenshot passed every check
// proof.status      → payment status after the check (e.g. "claimed")
// proof.utr         → 12-digit UTR read from the screenshot, or null
// proof.confidence  → 0..1
// proof.reasons     → why it was rejected (string[])

if (!proof.accepted) {
  // Do NOT deliver the goods
}

const { payments, hasMore, nextCursor } = await upi.listPayments({
  status: "claimed",
  limit: 20,
});

if (hasMore) {
  const next = await upi.listPayments({ status: "claimed", cursor: nextCursor! });
}

{
  "id": "uuid",
  "transactionId": "TXN_m4x7k2_a1b2c3",
  "amount": 499.37,
  "intentUrl": "upi://pay?pa=...&am=499.37&...",
  "qrDataUrl": "data:image/png;base64,...",
  "status": "pending",
  "expiresAt": "2026-05-03T10:50:00Z",
  "createdAt": "2026-05-03T10:30:00Z"
}

curl -X POST https://beta.upiagent.live/api/v1/payments/$ID/proof \
  -H "Authorization: Bearer $UPIAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "data:image/png;base64,iVBORw0KGgo...", "mediaType": "image/png"}'

{
  "accepted": true,
  "status": "claimed",
  "utr": "003538060093",
  "confidence": 0.96,
  "reasons": []
}

{
  "tokensToday": 4210,
  "dailyLimit": 20000,
  "remaining": 15790,
  "tier": "platform",
  "resetsAt": "2026-05-04T00:00:00Z"
}

{
  "event": "payment.verified",
  "timestamp": "2026-05-03T10:30:01Z",
  "deliveryId": "d_...",
  "data": {
    "paymentId": "uuid",
    "amount": 499.37,
    "currency": "INR",
    "status": "verified",
    "upiReferenceId": "003538060093",
    "senderName": "JOHN DOE",
    "confidence": 0.95,
    "verifiedAt": "2026-05-03T10:30:00Z"
  }
}

import { verifyWebhookSignature } from "upiagent";

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get("x-upiagent-signature")!;

  // WEBHOOK_SECRET = the hex secret from Dashboard → Settings
  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 401 });
  }

  const payload = JSON.parse(body);
  if (payload.event === "payment.verified") {
    // Bank-confirmed: fulfill the order
  } else if (payload.event === "payment.claimed") {
    // Screenshot passed all checks: OK for low-value goods
  } else if (payload.event === "payment.expired") {
    // Final: release any reserved stock
  }

  return new Response("ok");
}

{
  "mcpServers": {
    "upiagent": {
      "command": "npx",
      "args": ["-y", "upiagent", "mcp"],
      "env": { "UPIAGENT_API_KEY": "upi_ak_..." }
    }
  }
}

import { UpiAgent, UpiAgentApiError } from "upiagent/client";

const upi = new UpiAgent({ apiKey: process.env.UPIAGENT_API_KEY! });

try {
  const payment = await upi.createPayment({ amount: 499, addPaisa: true });
} catch (err) {
  if (err instanceof UpiAgentApiError) {
    console.error(err.status, err.message);
    // 401 → invalid API key
    // 429 → rate limit or daily token cap
    // 404 → payment not found
    // 409 → cancel on a payment that isn't pending
  }
}