Epayco

Copy code// One call from any Convex action — the charge runs, the result is persisted,
// and every subscribed client re-renders the moment the status changes.
const charge = await epayco.chargeCreditCard(ctx, { userId, chargeInfo });

Copy codenpm install @pulgueta/epayco-convex convex
# or: pnpm add @pulgueta/epayco-convex convex

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import epayco from "@pulgueta/epayco-convex/convex.config.js";

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

export default app;

Copy code// convex/payments.ts
import { v } from "convex/values";
import { EPayco } from "@pulgueta/epayco-convex";
import { components } from "./_generated/api";
import { action, query } from "./_generated/server";

// Construct once. Credentials come from EPAYCO_PUBLIC_KEY / EPAYCO_PRIVATE_KEY.
const epayco = new EPayco(components.epayco, { testMode: true });

export const charge = action({
  args: {
    tokenCard: v.string(),
    customerId: v.string(),
    value: v.number(),
  },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx); // your auth — see Security model
    return await epayco.chargeCreditCard(ctx, {
      userId,
      chargeInfo: {
        tokenCard: args.tokenCard,
        customerId: args.customerId,
        docType: "CC",
        docNumber: "1234567890",
        name: "Test",
        lastName: "User",
        email: "test@example.com",
        bill: "ORDER-1001",
        description: "Order #1001",
        value: args.value,
        tax: 0,
        taxBase: 0,
      },
    });
  },
});

// Reactive list — auto-updates when a webhook settles the payment.
export const myTransactions = query({
  args: {},
  handler: async (ctx) => {
    const userId = await requireUser(ctx);
    return await epayco.listTransactions(ctx, { userId });
  },
});

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

function Checkout() {
  const charge = useAction(api.payments.charge);
  const txs = useQuery(api.payments.myTransactions) ?? [];

  return (
    <>
      <button
        onClick={() =>
          charge({ tokenCard: "tok_xxx", customerId: "cust_xxx", value: 50000 })
        }
      >
        Pay $50.000
      </button>

      <ul>
        {txs.map((t) => (
          <li key={t.epaycoRef}>
            {t.epaycoRef} — {t.status} — ${t.amount.toLocaleString()}
          </li>
        ))}
      </ul>
    </>
  );
}

Copy codeconst epayco = new EPayco(components.epayco, {
  testMode: process.env.NODE_ENV !== "production",
});

Copy codeimport { usePayment, useTransactions } from "@pulgueta/epayco-convex/react";
import { api } from "../convex/_generated/api";

function PayButton() {
  const { execute, isLoading, error, result } = usePayment(api.payments.charge);

  return (
    <div>
      <button
        disabled={isLoading}
        onClick={() =>
          execute({ tokenCard: "tok_xxx", customerId: "cust_xxx", value: 50000 })
        }
      >
        {isLoading ? "Processing…" : "Pay"}
      </button>
      {error && <p role="alert">{error.message}</p>}
      {result && <p>Ref: {result.data?.ref_payco}</p>}
    </div>
  );
}

function History() {
  // Pass any reactive query that returns transactions.
  const txs = useTransactions(api.payments.myTransactions, {}) ?? [];
  return <ul>{txs.map((t) => <li key={t.epaycoRef}>{t.status}</li>)}</ul>;
}

Copy code// convex/cards.ts
import { v } from "convex/values";
import { EPayco } from "@pulgueta/epayco-convex";
import { components } from "./_generated/api";
import { action } from "./_generated/server";

const epayco = new EPayco(components.epayco, { testMode: true });

export const tokenize = action({
  args: { cardNumber: v.string(), expYear: v.string(), expMonth: v.string(), cvc: v.string() },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    return await epayco.createToken(ctx, { userId, tokenInfo: args });
  },
});

export const createCustomer = action({
  args: { tokenCard: v.string(), name: v.string(), lastName: v.string(), email: v.string() },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    // ePayco requires last_name — always send it.
    return await epayco.createCustomer(ctx, { userId, customerInfo: args });
  },
});

export const charge = action({
  args: { tokenCard: v.string(), customerId: v.string(), value: v.number() },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    return await epayco.chargeCreditCard(ctx, {
      userId,
      chargeInfo: {
        tokenCard: args.tokenCard,
        customerId: args.customerId,
        docType: "CC",
        docNumber: "1234567890",
        name: "Test",
        lastName: "User",
        email: "test@example.com",
        bill: "INV-1001",
        description: "Order #1001",
        value: args.value, // in COP, e.g. 50000 = $50.000
        tax: 0,            // IVA included in `value`
        taxBase: 0,        // taxable base
        dues: 1,           // installments
      },
    });
  },
});

Copy codeexport const banks = query({
  args: {},
  handler: (ctx) => epayco.listLocalBanks(ctx), // reactive, from the synced table
});

export const refreshBanks = action({
  args: {},
  handler: (ctx) => epayco.getBanks(ctx), // fetch + cache from ePayco
});

export const payWithPse = action({
  args: { bank: v.string(), value: v.number() },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    const result = await epayco.createPseTransaction(ctx, {
      userId,
      pseInfo: {
        bank: args.bank,
        typePerson: "0", // "0" natural person, "1" company
        docType: "CC",
        docNumber: "1234567890",
        name: "Test",
        lastName: "User",
        email: "test@example.com",
        cellPhone: "3001234567",
        bill: "INV-2001",
        description: "Order #2001",
        value: args.value,
        tax: 0,
        taxBase: 0,
        urlResponse: "https://your-app.com/pse/return",
      },
    });
    // result.data.urlbanco — redirect the buyer here.
    return result;
  },
});

Copy codeexport const payWithCash = action({
  args: {
    provider: v.union(
      v.literal("efecty"), v.literal("baloto"), v.literal("gana"),
      v.literal("redservi"), v.literal("puntored"), v.literal("sured"),
    ),
    value: v.number(),
  },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    return await epayco.createCashPayment(ctx, {
      userId,
      provider: args.provider,
      cashInfo: {
        docType: "CC",
        docNumber: "1234567890",
        name: "Test",
        lastName: "User",
        email: "test@example.com",
        cellPhone: "3001234567",
        bill: "INV-3001",
        description: "Order #3001",
        value: args.value,
        tax: 0,
        taxBase: 0,
        endDate: "2026-12-31", // voucher expiry (optional)
      },
    });
    // result.data.ref_payco + PIN/barcode → show to the buyer.
  },
});

Copy codeexport const startDaviplata = action({
  args: { value: v.number(), phone: v.string() },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    return await epayco.createDaviplataPayment(ctx, {
      userId,
      daviplataInfo: {
        docType: "CC",
        docNumber: "1234567890",
        name: "Test",
        lastName: "User",
        email: "test@example.com",
        phone: args.phone,
        description: "Order #4001",
        value: args.value,
        tax: 0,
        taxBase: 0,
      },
    });
    // → { data: { ref_payco, id_session_token } }
  },
});

export const confirmDaviplata = action({
  args: { refPayco: v.string(), idSessionToken: v.string(), otp: v.string() },
  handler: async (ctx, args) => {
    await requireUser(ctx);
    return await epayco.confirmDaviplataPayment(ctx, args);
  },
});

Copy codeexport const payWithSafetyPay = action({
  args: { value: v.number() },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    return await epayco.createSafetyPayPayment(ctx, {
      userId,
      safetypayInfo: {
        cash: "1", // "1" cash, "2" online bank
        docType: "CC",
        docNumber: "1234567890",
        name: "Test",
        lastName: "User",
        email: "test@example.com",
        phone: "3001234567",
        description: "Order #5001",
        value: args.value,
        tax: 0,
        taxBase: 0,
      },
    });
  },
});

Copy codeexport const createPlan = action({
  args: {},
  handler: async (ctx) => {
    await requireAdmin(ctx);
    return await epayco.createPlan(ctx, {
      planInfo: {
        idPlan: "pro-monthly",
        name: "Pro Monthly",
        description: "Pro plan billed monthly",
        amount: 49900,
        currency: "COP",
        interval: "month",
        intervalCount: 1,
        trialDays: 0,
      },
    });
  },
});

export const subscribe = action({
  args: { customer: v.string(), tokenCard: v.string() },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    return await epayco.createSubscription(ctx, {
      userId,
      subscriptionInfo: {
        idPlan: "pro-monthly",
        customer: args.customer,   // ePayco customer id
        tokenCard: args.tokenCard,
        docType: "CC",
        docNumber: "1234567890",
      },
    });
  },
});

export const cancel = action({
  args: { epaycoSubscriptionId: v.string() },
  handler: async (ctx, args) => {
    await requireUser(ctx);
    return await epayco.cancelSubscription(ctx, args);
  },
});

// Reactive: the current active subscription for the signed-in user.
export const activeSubscription = query({
  args: {},
  handler: async (ctx) => {
    const userId = await requireUser(ctx);
    return await epayco.getActiveSubscription(ctx, { userId });
  },
});

Copy codechargeInfo: {
  /* …normal fields… */
  split: {
    splitType: "02",
    splitReceivers: [
      { id: "1", total: "58000", iva: "8000", base_iva: "50000", fee: "10" },
    ],
  },
}

Copy code// convex/http.ts
import { httpRouter } from "convex/server";
import { registerRoutes } from "@pulgueta/epayco-convex";
import { components } from "./_generated/api";

const http = httpRouter();

registerRoutes(http, components.epayco, {
  pathPrefix: "/epayco", // default
  // custIdCliente / pKey default to EPAYCO_P_CUST_ID_CLIENTE / EPAYCO_P_KEY
});

export default http;

https://YOUR_DEPLOYMENT.convex.site/epayco/confirmation

Copy codeexport const myTransactions = query({
  args: { status: v.optional(v.string()) },
  handler: async (ctx, args) => {
    const userId = await requireUser(ctx);
    return await epayco.listTransactions(ctx, { userId, status: args.status });
  },
});

Copy code// convex/payments.ts
import { exposeApi } from "@pulgueta/epayco-convex";
import { components } from "./_generated/api";

export const {
  listTransactions,
  getTransaction,      // returns null unless the row belongs to the caller
  getCustomer,
  listSubscriptions,
  getActiveSubscription,
} = exposeApi(components.epayco, {
  auth: async (ctx, _operation) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthorized");
    return identity.subject; // this is the only scope these queries will use
  },
});

Copy code// client
const txs = useQuery(api.payments.listTransactions, {}) ?? [];
const sub = useQuery(api.payments.getActiveSubscription, {});

Copy codeimport type { Auth } from "convex/server";

async function requireUser(ctx: { auth: Auth }) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error("Unauthorized");
  return identity.subject;
}

Copy codefunction errMsg(err: unknown): string {
  if (err && typeof err === "object" && "data" in err) {
    const data = (err as { data?: { message?: unknown } }).data;
    if (data && typeof data.message === "string") return data.message;
  }
  return err instanceof Error ? err.message : "Something went wrong";
}

Copy codetry {
  await charge({ /* … */ });
} catch (err) {
  setError(errMsg(err)); // e.g. "La tarjeta fue rechazada"
}

Copy codepnpm test