Get started with upiagent

npm install upiagent

import { createPayment, fetchAndVerifyPayment } from "upiagent";

// Step 1 — Generate a payment QR code
const payment = await createPayment(
  { upiId: "yourshop@ybl", name: "Your Shop" },
  { amount: 499, note: "Order #123" }
);

// Show payment.qrDataUrl to the customer (it's a base64 PNG)
// Save payment.transactionId to your database

// Step 2 — After the customer pays, verify it
const result = await fetchAndVerifyPayment({
  gmail: {
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    refreshToken: process.env.GMAIL_REFRESH_TOKEN,
  },
  llm: {
    provider: "gemini",
    model: "gemini-2.0-flash",
    apiKey: process.env.GEMINI_API_KEY,
  },
  expected: { amount: 499 },
});

if (result.verified) {
  console.log("Payment confirmed!", result.payment);
}

import { createPayment } from "upiagent";

const payment = await createPayment(
  { upiId: "shop@ybl", name: "My Shop" },
  {
    amount: 299,
    note: "Order #456",
    addPaisa: true,  // adds random paisa for unique amount matching
  }
);

// payment.qrDataUrl      → base64 PNG, use in <img src={...} />
// payment.intentUrl      → upi://pay?pa=shop@ybl&am=299.42&...
// payment.transactionId  → "txn_a1b2c3d4"
// payment.amount         → 299.42 (with random paisa added)

import { createPaymentSvg } from "upiagent";

const payment = await createPaymentSvg(
  { upiId: "shop@ybl", name: "My Shop" },
  { amount: 299 }
);
// payment.qrDataUrl is now an SVG string

import { fetchAndVerifyPayment } from "upiagent";

const result = await fetchAndVerifyPayment({
  gmail: {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    refreshToken: "your-refresh-token",
  },
  llm: {
    provider: "gemini",
    model: "gemini-2.0-flash",
    apiKey: "your-gemini-key",
  },
  expected: {
    amount: 499,                  // exact amount to match
    timeWindowMinutes: 30,        // how far back to look (default: 30)
  },
  lookbackMinutes: 30,            // Gmail search window
  maxEmails: 10,                  // max emails to check
});

if (result.verified) {
  console.log(result.payment.senderName);       // "John Doe"
  console.log(result.payment.amount);           // 499
  console.log(result.payment.upiReferenceId);   // "412345678901"
  console.log(result.confidence);               // 0.95
}

import { verifyPayment } from "upiagent";

const result = await verifyPayment(email, {
  llm: {
    provider: "gemini",
    model: "gemini-2.0-flash",
    apiKey: "your-gemini-key",
  },
  expected: { amount: 499 },
});

// VerificationResult
{
  verified: true,            // did it pass all 5 layers?
  payment: {
    amount: 499,
    senderName: "John Doe",
    senderUpiId: "john@ybl",
    upiReferenceId: "412345678901",
    bankName: "HDFC Bank",
    receivedAt: "2025-01-15T10:30:00Z",
  },
  confidence: 0.95,          // LLM confidence (0-1)
  failureReason: null,       // or "AMOUNT_MISMATCH", "DUPLICATE", etc.
  layerResults: [            // step-by-step breakdown
    { layer: "email_source", passed: true },
    { layer: "amount_match", passed: true },
    { layer: "time_window", passed: true },
    { layer: "llm_confidence", passed: true },
    { layer: "dedup", passed: true },
  ],
}

import { fetchAndVerifyPayment, PostgresDedupStore } from "upiagent";

const dedup = new PostgresDedupStore(process.env.DATABASE_URL);

const result = await fetchAndVerifyPayment({
  // ... gmail, llm, expected
  dedup,
});

import { WebhookSender } from "upiagent";

const sender = new WebhookSender({
  url: "https://yourapp.com/webhooks/payment",
  secret: "whsec_your_secret_here",
});

// Send a payment.verified event
const delivery = await sender.send({
  event: "payment.verified",
  data: {
    paymentId: "txn_123",
    amount: 499,
    currency: "INR",
    status: "verified",
    upiReferenceId: "412345678901",
    senderName: "John Doe",
    confidence: 0.95,
  },
});

// delivery.delivered → true/false
// delivery.attempts  → number of attempts (retries on failure)

import { verifyWebhookSignature } from "upiagent";

// In your webhook handler (Express, Next.js, etc.)
const signature = req.headers["x-upiagent-signature"];
const event = req.headers["x-upiagent-event"];
const body = await req.text();

const isValid = verifyWebhookSignature(body, signature, "whsec_your_secret");

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

// Safe to process
const payload = JSON.parse(body);
if (payload.event === "payment.verified") {
  // credit the customer
}

npx upiagent setup

// Gemini (free, default)
llm: { provider: "gemini", model: "gemini-2.0-flash", apiKey: "..." }

// OpenAI
llm: { provider: "openai", model: "gpt-4o-mini", apiKey: "..." }

// Anthropic
llm: { provider: "anthropic", model: "claude-3-haiku-20240307", apiKey: "..." }

import {
  GmailAuthError,
  GmailRateLimitError,
  LlmError,
  LlmRateLimitError,
  LlmBudgetExceededError,
  ConfigError,
} from "upiagent";

try {
  const result = await fetchAndVerifyPayment({ ... });
} catch (err) {
  if (err instanceof GmailAuthError) {
    // Gmail OAuth token expired — re-authenticate
  }
  if (err instanceof GmailRateLimitError) {
    // Gmail API rate limit — back off and retry
  }
  if (err instanceof LlmError) {
    // LLM API call failed — check your API key
  }
  if (err instanceof LlmRateLimitError) {
    // LLM rate limit — use the built-in LlmRateLimiter
  }
  if (err instanceof LlmBudgetExceededError) {
    // Token budget exceeded — use CostTracker to set limits
  }
}

// app/api/create-payment/route.ts
import { createPayment } from "upiagent";

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

  const payment = await createPayment(
    { upiId: process.env.UPI_ID!, name: "My Store" },
    { amount, note, addPaisa: true }
  );

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

import express from "express";
import { createPayment, fetchAndVerifyPayment } from "upiagent";

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

app.post("/pay", async (req, res) => {
  const payment = await createPayment(
    { upiId: "shop@ybl", name: "My Shop" },
    { amount: req.body.amount, addPaisa: true }
  );
  res.json(payment);
});

app.post("/verify", async (req, res) => {
  const result = await fetchAndVerifyPayment({
    gmail: { /* credentials */ },
    llm: { provider: "gemini", model: "gemini-2.0-flash", apiKey: "..." },
    expected: { amount: req.body.amount },
  });
  res.json({ verified: result.verified, payment: result.payment });
});

app.listen(3000);

// app/api/webhooks/payment/route.ts
import { verifyWebhookSignature } from "upiagent";

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

  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") {
    // Update order status, send confirmation email, etc.
    console.log("Payment verified:", payload.data.paymentId);
  }

  return new Response("ok");
}