OxaPay

Copy codenpm install convex-oxapay

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import oxapay from "convex-oxapay/convex.config";

const app = defineApp();
app.use(oxapay);

export default app;

Copy codenpx convex env set OXAPAY_MERCHANT_API_KEY  XXXXXX-XXXXXX-XXXXXX-XXXXXX
# Only needed if you create payouts:
npx convex env set OXAPAY_PAYOUT_API_KEY    XXXXXX-XXXXXX-XXXXXX-XXXXXX
# Only needed if you call /general (swap, balance):
npx convex env set OXAPAY_GENERAL_API_KEY   XXXXXX-XXXXXX-XXXXXX-XXXXXX
# Optional: defaults to false. Send sandbox: true on all createInvoice calls.
npx convex env set OXAPAY_SANDBOX           true

Copy code// convex/oxapay.ts
import { OxaPay } from "convex-oxapay";
import { components } from "./_generated/api";

export const oxapay = new OxaPay(components.oxapay, {
  // All fields are optional. Defaults come from env vars.
  merchantApiKey: process.env.OXAPAY_MERCHANT_API_KEY,
  payoutApiKey:   process.env.OXAPAY_PAYOUT_API_KEY,
  generalApiKey:  process.env.OXAPAY_GENERAL_API_KEY,
  baseUrl:        process.env.OXAPAY_BASE_URL,        // for proxies / mocks
  defaultCallbackUrl:
    "https://your-app.convex.site/oxapay/webhook",   // auto-sent on every payment
  sandbox: false,                                     // send sandbox: true by default
});

Copy code// convex/payments.ts
import { v } from "convex/values";
import { action, query } from "./_generated/server";
import { oxapay } from "./oxapay";

/** Create a USD-priced crypto invoice and return its hosted URL. */
export const createInvoice = action({
  args: { amount: v.number() },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity?.subject) throw new Error("Not authenticated");

    const { trackId, paymentUrl } = await oxapay.payments.createInvoice(ctx, {
      entityId: identity.subject,        // links this payment to your user
      amount: args.amount,
      currency: "USD",
      description: "Premium upgrade",
      orderId: identity.subject,         // round-tripped to the webhook
      lifetime: 60,                      // minutes (15..2880)
    });

    return { trackId, paymentUrl };
  },
});

/** Live status query. Re-renders whenever the webhook updates the mirror. */
export const getPayment = query({
  args: { trackId: v.string() },
  handler: async (ctx, args) => {
    return await oxapay.payments.get(ctx, { trackId: args.trackId });
  },
});

Copy codeimport { useState } from "react";
import { useAction, useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

function PaymentFlow() {
  const [trackId, setTrackId] = useState<string | null>(null);
  const createInvoice = useAction(api.payments.createInvoice);
  const payment = useQuery(
    api.payments.getPayment,
    trackId ? { trackId } : "skip",
  );

  return (
    <>
      <button
        onClick={async () => {
          const { trackId, paymentUrl } = await createInvoice({ amount: 25 });
          setTrackId(trackId);
          window.open(paymentUrl, "_blank");
        }}
      >
        Pay $25 with crypto
      </button>

      {payment && (
        <p>
          Status: <strong>{payment.status}</strong>
        </p>
      )}
    </>
  );
}

Copy code// convex/http.ts
import { httpRouter } from "convex/server";
import { internal } from "./_generated/api";
import { oxapay } from "./oxapay";

const http = httpRouter();

oxapay.registerRoutes(http, {
  path: "/oxapay/webhook",         // default
  events: {
    // Fires for invoice / white-label / static-address payments
    "payment.paid": async (ctx, event) => {
      // event.order_id is whatever you sent at creation
      await ctx.runMutation(internal.users.markPremium, {
        entityId: (event as any).order_id,
      });
    },
    "payment.expired": async (ctx, event) => {
      console.log("expired", (event as any).track_id);
    },
    "payout.confirmed": async (ctx, event) => {
      console.log("payout confirmed", (event as any).track_id);
    },
  },
});

export default http;

https://<your-deployment>.convex.site/oxapay/webhook

Copy code{
  entityId: string | null;        // your app's user/org id, or null for anonymous
  amount: number;                 // priced amount
  currency?: string;              // default "USD"; supports fiats and cryptos
  lifetime?: number;              // minutes, 15..2880, default 60
  feePaidByPayer?: 0 | 1;         // who pays the OxaPay fee
  underPaidCoverage?: number;     // %, 0..60
  toCurrency?: string;            // auto-convert receipts into this crypto
  autoWithdrawal?: boolean;       // sweep to your linked external wallet
  mixedPayment?: boolean;         // allow paying remainder in a 2nd coin
  callbackUrl?: string;           // override the default callback URL
  returnUrl?: string;
  email?: string;
  orderId?: string;               // round-tripped to the webhook
  thanksMessage?: string;
  description?: string;
  sandbox?: boolean;              // override the global sandbox flag
  metadata?: Record<string, unknown>;  // stored on the mirror row
}

Copy codeconst { trackId, address, qrCode } = await oxapay.staticAddresses.create(ctx, {
  entityId: identity.subject,
  network: "Tron",          // "Bitcoin" | "Ethereum" | "Tron" | "BSC" | etc.
  toCurrency: "USDT",       // auto-convert receipts into USDT
  autoWithdrawal: false,
  description: "Wallet top-up",
});

Copy codeconst { trackId, status } = await oxapay.payouts.create(ctx, {
  entityId: userId,
  address: "1A1z7agoat...",
  currency: "BTC",
  network: "Bitcoin",
  amount: 0.5,
  description: "Withdrawal request #42",
});

Copy codeconst { rate } = await oxapay.swap.rate({ fromCurrency: "BTC", toCurrency: "USDT" });
const { toAmount } = await oxapay.swap.calculate({ fromCurrency: "BTC", toCurrency: "USDT", amount: 0.01 });
const swap = await oxapay.swap.execute({ fromCurrency: "BTC", toCurrency: "USDT", amount: 0.01 });
const { list } = await oxapay.swap.pairs();
const history = await oxapay.swap.history({ size: 50 });

Copy codeconst balance = await oxapay.account.balance();
// { BTC: { available: 0.5, pending: 0 }, USDT: { available: 100, pending: 5 } }
const { list } = await oxapay.account.acceptedCurrencies();

Copy codeawait oxapay.common.prices();      // { BTC: 79105.23, ETH: 2228.58, ... }
await oxapay.common.currencies();  // { BTC: { networks: { Bitcoin: { withdraw_fee, ... } } } }
await oxapay.common.fiats();       // { USD: { price: 1, display_precision: 0.001 }, ... }
await oxapay.common.networks();    // { list: ["Bitcoin Network", "Ethereum Network", ...] }
await oxapay.common.monitor();     // { status: "OK" }

Copy codeoxapay.registerRoutes(http, {
  path: "/oxapay/webhook",        // default
  events: { "payment.paid": handler, "payout.confirmed": handler, ... },
  onEvent: async (ctx, event) => { /* catch-all */ },
});

Copy code// convex/oxapay.ts (continued)
export const {
  createInvoice,
  createWhiteLabel,
  createStaticAddress,
  createPayout,
  refreshPayment,
  listMyPayments,
  listMyPayouts,
} = oxapay.api({
  resolve: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) return null;
    return { entityId: identity.subject };
  },
});

Copy codeconst createInvoice = useAction(api.oxapay.createInvoice);
const myPayments    = useAction(api.oxapay.listMyPayments);

Copy codeimport { OxaPayCheckoutButton } from "convex-oxapay/react";
import { api } from "../convex/_generated/api";

<OxaPayCheckoutButton
  createInvoice={api.oxapay.createInvoice}
  invoiceArgs={{ amount: 50, currency: "USD" }}
  mode="new-tab"                       // "redirect" | "new-tab" | "none"
  onCreated={(r) => console.log(r)}
  onError={(e) => alert("Failed: " + e)}
>
  Pay $50 with crypto
</OxaPayCheckoutButton>

Copy codeimport { useOxaPayPayment } from "convex-oxapay/react";
import { api } from "../convex/_generated/api";

function Status({ trackId }: { trackId: string }) {
  const payment = useOxaPayPayment(api.payments.getPayment, trackId);
  if (!payment) return <p>Loading…</p>;
  return <p>Status: {payment.status}</p>;
}

new → waiting → paying → paid           ← happy path
                      ↘ underpaid       ← partial payment
                      ↘ expired         ← lifetime elapsed
              paid → refunding → refunded

processing → pending → confirming → confirmed
                                  ↘ rejected
                                  ↘ canceled

Copy codeevents: {
  "payment.paid":     async (ctx, e) => { /* fulfill order */ },
  "payment.expired":  async (ctx, e) => { /* mark expired   */ },
  "payment.underpaid": async (ctx, e) => { /* notify support */ },
  "payout.confirmed": async (ctx, e) => { /* mark withdrawal complete */ },
  "payout.rejected":  async (ctx, e) => { /* refund the user */ },
}

Copy code// example/convex/setup.test.ts
import { convexTest } from "convex-test";
import schema from "./schema";
import component from "convex-oxapay/test";

const modules = import.meta.glob("./**/*.ts");

export function initConvexTest() {
  const t = convexTest(schema, modules);
  component.register(t);    // registers the "oxapay" component
  return t;
}

Copy codegit clone https://github.com/bradperbs/convex-oxapay
cd convex-oxapay
npm install
npm run dev          # convex dev + watcher rebuilding TS
npm run dev:frontend # runs the example/ React app on Vite
npm test
npm run build

Copy codeVITE_CONVEX_URL=https://<your-deployment>.convex.cloud