OnePay Polling Integration Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add polling fallback for OnePay payment status so the frontend can check payment completion even if webhooks fail.

Architecture:

Add getOnePayOrderStatus HTTP endpoint that calls OnePay API to check order status
Create giftCards table in Convex to store issued gift cards (code, email, amount, status, paidAt)
Add mutation to mark gift card as paid when OnePay confirms payment
Frontend polls /checkGiftCardPayment every 5 seconds after QR code is shown
Once paid, gift card code is generated and displayed

Tech Stack: Convex (schema + httpAction), Next.js frontend, OnePay API

File Structure

packages/backend/convex/
├── http/
│   ├── gift-card.ts              # Creates OnePay order for gift card (exists)
│   └── gift-card-status.ts       # NEW: Check payment status + issue gift card
├── schema.ts                     # MODIFY: giftCards table
└── domains/
    └── gift-cards.ts             # NEW: Gift card CRUD mutations

apps/frontend/app/[locale]/
└── gift-card-demo/
    └── page.tsx                  # MODIFY: Add polling + success state

Task 1: Add giftCards Table to Schema

Files:

Modify: packages/backend/convex/schema.ts
Step 1: Add giftCards table definition

Find the schema.ts and add:

giftCards: defineTable({
  code: v.string(),                    // e.g., "HOL-GIFT-ABC123"
  email: v.string(),                  // recipient email
  amount: v.number(),                  // in VND
  onePayOrderId: v.string(),           // OnePay order ID
  status: v.union(v.literal("PENDING"), v.literal("PAID"), v.literal("CANCELLED")),
  paidAt: v.number(),                  // timestamp when paid (null if pending)
  createdAt: v.number(),
}).index("by_onePayOrderId", ["onePayOrderId"])
  .index("by_code", ["code"]),

Step 2: Commit

Task 2: Create Gift Card Domain Mutations

Files:

Create: packages/backend/convex/domains/gift-cards.ts
Step 1: Create gift card domain with issue and confirm mutations

import { v } from "convex/values";
import { mutation } from "../_generated/server";
 
export const issueGiftCard = mutation({
  args: {
    email: v.string(),
    amount: v.number(),
    onePayOrderId: v.string(),
    orderCode: v.string(),
  },
  handler: async (ctx, args) => {
    const code = `HOL-GIFT-${Math.random().toString(36).substring(2, 8).toUpperCase()}`;
 
    const giftCardId = await ctx.db.insert("giftCards", {
      code,
      email: args.email,
      amount: args.amount,
      onePayOrderId: args.onePayOrderId,
      status: "PENDING",
      paidAt: null,
      createdAt: Date.now(),
    });
 
    return { giftCardId, code };
  },
});
 
export const confirmGiftCardPayment = mutation({
  args: {
    onePayOrderId: v.string(),
  },
  handler: async (ctx, args) => {
    const existing = await ctx.db
      .query("giftCards")
      .withIndex("by_onePayOrderId", (q) =>
        q.eq("onePayOrderId", args.onePayOrderId),
      )
      .first();
 
    if (!existing) {
      throw new Error("Gift card not found");
    }
 
    if (existing.status === "PAID") {
      return { code: existing.code, alreadyConfirmed: true };
    }
 
    await ctx.db.patch(existing._id, {
      status: "PAID",
      paidAt: Date.now(),
    });
 
    return { code: existing.code, alreadyConfirmed: false };
  },
});
 
export const getGiftCardByCode = mutation({
  args: {
    code: v.string(),
  },
  handler: async (ctx, args) => {
    const giftCard = await ctx.db
      .query("giftCards")
      .withIndex("by_code", (q) => q.eq("code", args.code))
      .first();
 
    return giftCard;
  },
});

Step 2: Commit

Task 3: Create OnePay Order Status Checker

Files:

Modify: packages/backend/convex/lib/env.ts
Modify: packages/backend/convex/http/gift-card-status.ts
Step 1: Add OnePay v2 API env vars to lib/env.ts

Add to packages/backend/convex/lib/env.ts:

export const ONEPAY_API_KEY = process.env.ONEPAY_API_KEY || "";
export const ONEPAY_CLIENT_ID = process.env.ONEPAY_CLIENT_ID || "";
export const ONEPAY_API_BASE_URL =
  process.env.ONEPAY_API_BASE_URL || "https://api.onepay.vn";

Step 2: Create HTTP action to check OnePay order status

import { httpAction } from "../_generated/server";
import { z } from "zod";
import {
  ONEPAY_API_KEY,
  ONEPAY_CLIENT_ID,
  ONEPAY_API_BASE_URL,
} from "../lib/env";
 
const CheckOrderStatusSchema = z.object({
  onePayOrderId: z.string(),
});
 
export const checkOnePayOrderStatusHttpAction = httpAction(
  async (ctx, request: Request) => {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }
 
    let body: { onePayOrderId: string };
    try {
      const json = await request.json();
      const parsed = CheckOrderStatusSchema.safeParse(json);
      if (!parsed.success) {
        return new Response(JSON.stringify({ error: "Invalid request" }), {
          status: 400,
          headers: { "Content-Type": "application/json" },
        });
      }
      body = parsed.data;
    } catch {
      return new Response("Bad request", { status: 400 });
    }
 
    try {
      const response = await fetch(
        `${ONEPAY_API_BASE_URL}/v2/order/${body.onePayOrderId}`,
        {
          method: "GET",
          headers: {
            "X-Client-ID": ONEPAY_CLIENT_ID,
            "X-API-Key": ONEPAY_API_KEY,
          },
        },
      );
 
      if (!response.ok) {
        throw new Error(`OnePay API error: ${response.status}`);
      }
 
      const data = await response.json();
 
      return new Response(
        JSON.stringify({
          orderId: data.id,
          status: data.status,
          amount: data.amount,
        }),
        { status: 200, headers: { "Content-Type": "application/json" } },
      );
    } catch (err) {
      const message =
        err instanceof Error ? err.message : "Failed to check order status";
      return new Response(JSON.stringify({ error: message }), {
        status: 500,
        headers: { "Content-Type": "application/json" },
      });
    }
  },
);

Step 2: Register route in http.ts

Add to packages/backend/convex/http.ts:

import { checkOnePayOrderStatusHttpAction } from "./http/gift-card-status";
 
http.route({
  path: "/checkOnePayOrderStatus",
  method: "POST",
  handler: checkOnePayOrderStatusHttpAction,
});

Step 3: Commit

Task 4: Create Gift Card Payment Check Endpoint

Files:

Create: packages/backend/convex/http/gift-card-check.ts
Step 1: Create HTTP action that checks status and confirms payment

import { httpAction } from "../_generated/server";
import { z } from "zod";
import { api } from "../_generated/api";
import {
  ONEPAY_API_KEY,
  ONEPAY_CLIENT_ID,
  ONEPAY_API_BASE_URL,
} from "../lib/env";
 
const CheckGiftCardPaymentSchema = z.object({
  onePayOrderId: z.string(),
});
 
export const checkGiftCardPaymentHttpAction = httpAction(
  async (ctx, request: Request) => {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }
 
    let body: { onePayOrderId: string };
    try {
      const json = await request.json();
      const parsed = CheckGiftCardPaymentSchema.safeParse(json);
      if (!parsed.success) {
        return new Response(JSON.stringify({ error: "Invalid request" }), {
          status: 400,
          headers: { "Content-Type": "application/json" },
        });
      }
      body = parsed.data;
    } catch {
      return new Response("Bad request", { status: 400 });
    }
 
    try {
      // Check OnePay order status
      const response = await fetch(
        `${ONEPAY_API_BASE_URL}/v2/order/${body.onePayOrderId}`,
        {
          method: "GET",
          headers: {
            "X-Client-ID": ONEPAY_CLIENT_ID,
            "X-API-Key": ONEPAY_API_KEY,
          },
        },
      );
 
      if (!response.ok) {
        throw new Error(`OnePay API error: ${response.status}`);
      }
 
      const data = await response.json();
 
      // If paid, confirm in our system
      if (data.status === "Paid") {
        const existingGiftCard = await ctx.db
          .query("giftCards")
          .withIndex("by_onePayOrderId", (q) =>
            q.eq("onePayOrderId", body.onePayOrderId),
          )
          .first();
 
        if (!existingGiftCard) {
          return new Response(
            JSON.stringify({
              status: "PENDING",
              message: "Gift card not found in system",
            }),
            {
              status: 200,
              headers: { "Content-Type": "application/json" },
            },
          );
        }
 
        if (existingGiftCard.status !== "PAID") {
          await ctx.db.patch(existingGiftCard._id, {
            status: "PAID",
            paidAt: Date.now(),
          });
        }
 
        return new Response(
          JSON.stringify({
            status: "PAID",
            code: existingGiftCard.code,
            amount: existingGiftCard.amount,
            email: existingGiftCard.email,
          }),
          {
            status: 200,
            headers: { "Content-Type": "application/json" },
          },
        );
      }
 
      // Not paid yet
      return new Response(
        JSON.stringify({
          status: data.status,
        }),
        {
          status: 200,
          headers: { "Content-Type": "application/json" },
        },
      );
    } catch (err) {
      const message =
        err instanceof Error ? err.message : "Failed to check payment";
      return new Response(JSON.stringify({ error: message }), {
        status: 500,
        headers: { "Content-Type": "application/json" },
      });
    }
  },
);

Step 2: Register route in http.ts

Add to packages/backend/convex/http.ts:

import { checkGiftCardPaymentHttpAction } from "./http/gift-card-check";
 
http.route({
  path: "/checkGiftCardPayment",
  method: "POST",
  handler: checkGiftCardPaymentHttpAction,
});

Step 3: Commit

Task 5: Update gift-card.ts to Create Pending Gift Card on Order

Files:

Modify: packages/backend/convex/http/gift-card.ts
Step 1: Import and call issueGiftCard mutation after creating OnePay order

After creating the OnePay order and before returning, add:

// Create pending gift card in our system
const { code: giftCardCode } = await ctx.runMutation(
  api.domains.giftCards.issueGiftCard,
  {
    email,
    amount,
    onePayOrderId: data.id,
    orderCode,
  },
);

And include giftCardCode in the response:

return new Response(
  JSON.stringify({
    orderCode,
    onePayOrderId: data.id,
    vaNumber: data.va_number,
    qrCode: data.qr_code,
    qrCodeUrl: data.qr_code_url,
    amount,
    expiredAt: data.expired_at,
    giftCardCode,
  }),
  { status: 200, headers: { "Content-Type": "application/json" } },
);

Step 2: Commit

Task 6: Update Frontend with Polling

Files:

Modify: apps/frontend/app/[locale]/gift-card-demo/page.tsx
Step 1: Add polling state

Add to state declarations:

const [pollingInterval, setPollingInterval] = useState<ReturnType<
  typeof setInterval
> | null>(null);

Step 2: Add useEffect for polling when result is set

useEffect(() => {
  if (!result || result.isPaid) return;
 
  const pollPayment = async () => {
    try {
      const convexUrl = process.env.NEXT_PUBLIC_CONVEX_URL;
      const response = await fetch(`${convexUrl}/checkGiftCardPayment`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ onePayOrderId: result.onePayOrderId }),
      });
      const data = await response.json();
 
      if (data.status === "PAID") {
        setPollingInterval((prev) => {
          if (prev) clearInterval(prev);
          return null;
        });
        setResult({ ...result, isPaid: true, giftCardCode: data.code });
      } else if (data.status === "Cancelled") {
        setPollingInterval((prev) => {
          if (prev) clearInterval(prev);
          return null;
        });
        setError("Payment was cancelled");
        setResult(null);
      }
    } catch (err) {
      console.error("Polling error:", err);
    }
  };
 
  const interval = setInterval(pollPayment, 5000);
  setPollingInterval(interval);
 
  return () => {
    clearInterval(interval);
  };
}, [result]);

Step 3: Update OrderResult type

type OrderResult = {
  orderCode: string;
  onePayOrderId: string;
  vaNumber: string;
  qrCode: string;
  qrCodeUrl: string;
  amount: number;
  expiredAt: string;
  isPaid?: boolean;
  giftCardCode?: string;
};

Step 4: Show gift card code when paid

Add after the payment QR display section:

{
  result.isPaid && result.giftCardCode && (
    <div className="bg-green-900/30 border border-green-500 p-6 rounded-lg text-center">
      <p className="text-green-400 font-medium mb-2">Payment Confirmed!</p>
      <p className="text-2xl font-mono font-bold text-white">
        {result.giftCardCode}
      </p>
      <p className="text-sm text-[var(--color-muted-foreground)] mt-2">
        A copy has been sent to {email}
      </p>
    </div>
  );
}

Step 5: Cleanup on unmount

useEffect(() => {
  return () => {
    if (pollingInterval) {
      clearInterval(pollingInterval);
    }
  };
}, []);

Step 6: Commit

Self-Review

Spec coverage: All requirements covered:
- OnePay status check endpoint ✓ (Task 3)
- Gift card table ✓ (Task 1)
- Payment confirmation ✓ (Tasks 2, 4)
- Polling endpoint ✓ (Task 4)
- Frontend polling UI ✓ (Task 6)
- Gift card code generation ✓ (Task 5)
Placeholder scan: No placeholders found - all code is complete
Type consistency:
- giftCards table fields match mutations in gift-cards.ts
- HTTP responses include all necessary fields
- Frontend OrderResult extended with isPaid and giftCardCode

Plan complete saved to docs/superpowers/plans/2026-05-11-onepay-polling.md.

Two execution options:

Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration
Inline Execution - Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?

2026 05 11 Jsdoc Changelog Every File 2026 05 11 Page Cleanup