@pulgueta/epayco-convex 0.1.0

package/src/component/validators.ts

@@ -0,0 +1,245 @@
+import { v } from "convex/values";
+
+/**
+ * Credentials accepted by every component action. The host app passes these in
+ * from its own environment (see `EPayco` client wrapper). `apiKey` is the
+ * ePayco PUBLIC_KEY and `privateKey` is the PRIVATE_KEY.
+ */
+export const epaycoCredentialsValidator = v.object({
+  apiKey: v.string(),
+  privateKey: v.string(),
+  testMode: v.optional(v.boolean()),
+  lang: v.optional(v.string()),
+});
+
+export type EPaycoCredentials = {
+  apiKey: string;
+  privateKey: string;
+  testMode?: boolean;
+  lang?: string;
+};
+
+/** A split-payment receiver (used by charge / PSE / cash dispersion). */
+export const splitReceiverValidator = v.object({
+  id: v.string(),
+  total: v.string(),
+  iva: v.string(),
+  base_iva: v.string(),
+  fee: v.optional(v.string()),
+});
+
+/** Optional split-payment configuration shared by charge / PSE / cash. */
+export const splitPaymentValidator = v.object({
+  splitType: v.optional(v.string()),
+  splitAppId: v.optional(v.string()),
+  splitMerchantId: v.optional(v.string()),
+  splitPrimaryReceiver: v.optional(v.string()),
+  splitPrimaryReceiverFee: v.optional(v.string()),
+  splitRule: v.optional(v.string()),
+  splitReceivers: v.optional(v.array(splitReceiverValidator)),
+});
+
+export const customerInfoValidator = v.object({
+  tokenCard: v.string(),
+  name: v.string(),
+  lastName: v.optional(v.string()),
+  email: v.string(),
+  phone: v.optional(v.string()),
+  cellPhone: v.optional(v.string()),
+  docType: v.optional(v.string()),
+  docNumber: v.optional(v.string()),
+  isDefault: v.optional(v.boolean()),
+  city: v.optional(v.string()),
+  address: v.optional(v.string()),
+});
+
+export const tokenInfoValidator = v.object({
+  cardNumber: v.string(),
+  expYear: v.string(),
+  expMonth: v.string(),
+  cvc: v.string(),
+  hasCvv: v.optional(v.boolean()),
+});
+
+export const chargeInfoValidator = v.object({
+  tokenCard: v.string(),
+  customerId: v.string(),
+  docType: v.string(),
+  docNumber: v.string(),
+  name: v.string(),
+  lastName: v.string(),
+  email: v.string(),
+  city: v.optional(v.string()),
+  address: v.optional(v.string()),
+  phone: v.optional(v.string()),
+  cellPhone: v.optional(v.string()),
+  bill: v.string(),
+  description: v.string(),
+  value: v.number(),
+  tax: v.number(),
+  taxBase: v.number(),
+  currency: v.optional(v.string()),
+  dues: v.optional(v.number()),
+  ip: v.optional(v.string()),
+  urlResponse: v.optional(v.string()),
+  urlConfirmation: v.optional(v.string()),
+  methodConfirmation: v.optional(v.string()),
+  useDefaultCardCustomer: v.optional(v.boolean()),
+  extra1: v.optional(v.string()),
+  extra2: v.optional(v.string()),
+  extra3: v.optional(v.string()),
+  split: v.optional(splitPaymentValidator),
+});
+
+export const pseInfoValidator = v.object({
+  bank: v.string(),
+  typePerson: v.union(v.literal("0"), v.literal("1")),
+  docType: v.string(),
+  docNumber: v.string(),
+  name: v.string(),
+  lastName: v.string(),
+  email: v.string(),
+  cellPhone: v.string(),
+  country: v.optional(v.string()),
+  bill: v.string(),
+  description: v.string(),
+  value: v.number(),
+  tax: v.number(),
+  taxBase: v.number(),
+  currency: v.optional(v.string()),
+  ip: v.optional(v.string()),
+  urlResponse: v.optional(v.string()),
+  urlConfirmation: v.optional(v.string()),
+  extra1: v.optional(v.string()),
+  extra2: v.optional(v.string()),
+  extra3: v.optional(v.string()),
+  split: v.optional(splitPaymentValidator),
+});
+
+export const cashProviderValidator = v.union(
+  v.literal("efecty"),
+  v.literal("baloto"),
+  v.literal("gana"),
+  v.literal("redservi"),
+  v.literal("puntored"),
+  v.literal("sured"),
+);
+
+export const cashInfoValidator = v.object({
+  docType: v.string(),
+  docNumber: v.string(),
+  typePerson: v.optional(v.union(v.literal("0"), v.literal("1"))),
+  name: v.string(),
+  lastName: v.string(),
+  email: v.string(),
+  cellPhone: v.string(),
+  bill: v.string(),
+  description: v.string(),
+  value: v.number(),
+  tax: v.number(),
+  taxBase: v.number(),
+  currency: v.optional(v.string()),
+  ip: v.optional(v.string()),
+  urlResponse: v.optional(v.string()),
+  urlConfirmation: v.optional(v.string()),
+  endDate: v.optional(v.string()),
+  extra1: v.optional(v.string()),
+  extra2: v.optional(v.string()),
+  extra3: v.optional(v.string()),
+  split: v.optional(splitPaymentValidator),
+});
+
+export const daviplataInfoValidator = v.object({
+  docType: v.string(),
+  docNumber: v.string(),
+  name: v.string(),
+  lastName: v.string(),
+  email: v.string(),
+  indCountry: v.optional(v.string()),
+  phone: v.string(),
+  country: v.optional(v.string()),
+  city: v.optional(v.string()),
+  address: v.optional(v.string()),
+  ip: v.optional(v.string()),
+  description: v.string(),
+  value: v.number(),
+  tax: v.number(),
+  taxBase: v.number(),
+  currency: v.optional(v.string()),
+  methodConfirmation: v.optional(v.string()),
+  urlConfirmation: v.optional(v.string()),
+});
+
+export const safetypayInfoValidator = v.object({
+  cash: v.union(v.literal("1"), v.literal("2")),
+  endDate: v.optional(v.string()),
+  docType: v.string(),
+  docNumber: v.string(),
+  name: v.string(),
+  lastName: v.string(),
+  email: v.string(),
+  indCountry: v.optional(v.string()),
+  phone: v.string(),
+  country: v.optional(v.string()),
+  city: v.optional(v.string()),
+  address: v.optional(v.string()),
+  invoice: v.optional(v.string()),
+  ip: v.optional(v.string()),
+  description: v.string(),
+  value: v.number(),
+  tax: v.number(),
+  ico: v.optional(v.number()),
+  taxBase: v.number(),
+  currency: v.optional(v.string()),
+  methodConfirmation: v.optional(v.string()),
+  urlConfirmation: v.optional(v.string()),
+});
+
+export const planInfoValidator = v.object({
+  idPlan: v.string(),
+  name: v.string(),
+  description: v.string(),
+  amount: v.number(),
+  currency: v.string(),
+  interval: v.string(),
+  intervalCount: v.number(),
+  trialDays: v.number(),
+  iva: v.optional(v.number()),
+  ico: v.optional(v.number()),
+});
+
+export const subscriptionInfoValidator = v.object({
+  idPlan: v.string(),
+  customer: v.string(),
+  tokenCard: v.string(),
+  docType: v.string(),
+  docNumber: v.string(),
+  urlConfirmation: v.optional(v.string()),
+  methodConfirmation: v.optional(v.string()),
+});
+
+export const paymentMethodValidator = v.union(
+  v.literal("credit_card"),
+  v.literal("pse"),
+  v.literal("cash"),
+  v.literal("daviplata"),
+  v.literal("safetypay"),
+);
+
+export const transactionStatusValidator = v.union(
+  v.literal("pending"),
+  v.literal("approved"),
+  v.literal("rejected"),
+  v.literal("failed"),
+  v.literal("expired"),
+  v.literal("reversed"),
+);
+
+/** Split receivers persisted on a transaction (numeric form for local use). */
+export const storedSplitReceiverValidator = v.object({
+  id: v.string(),
+  total: v.number(),
+  iva: v.number(),
+  base_iva: v.number(),
+  fee: v.optional(v.number()),
+});

package/src/component/webhooks.test.ts

@@ -0,0 +1,137 @@
+/// <reference types="vite/client" />
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { initConvexTest } from "./setup.test.helper.js";
+import { internal } from "./_generated/api.js";
+
+describe("webhooks", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("storeWebhookEvent creates a new event", async () => {
+    const t = initConvexTest();
+    const id = await t.mutation(internal.webhooks.storeWebhookEvent, {
+      epaycoRef: "ref_w001",
+      eventType: "confirmation",
+      status: "pending",
+      rawPayload: { x_ref_payco: "ref_w001", x_cod_response: "1" },
+      lastSyncedAt: 1000,
+    });
+    expect(id).toBeDefined();
+
+    const event = await t.query(internal.webhooks.getWebhookEvent, {
+      epaycoRef: "ref_w001",
+    });
+    expect(event).not.toBeNull();
+    expect(event!.status).toBe("pending");
+    expect(event!.eventType).toBe("confirmation");
+  });
+
+  test("markWebhookProcessed updates event status", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.webhooks.storeWebhookEvent, {
+      epaycoRef: "ref_w002",
+      eventType: "confirmation",
+      status: "pending",
+      rawPayload: {},
+      lastSyncedAt: 1000,
+    });
+
+    await t.mutation(internal.webhooks.markWebhookProcessed, {
+      epaycoRef: "ref_w002",
+      status: "processed",
+    });
+
+    const event = await t.query(internal.webhooks.getWebhookEvent, {
+      epaycoRef: "ref_w002",
+    });
+    expect(event!.status).toBe("processed");
+    expect(event!.processedAt).toBeDefined();
+  });
+
+  test("markWebhookProcessed with error message", async () => {
+    const t = initConvexTest();
+    await t.mutation(internal.webhooks.storeWebhookEvent, {
+      epaycoRef: "ref_w003",
+      eventType: "confirmation",
+      status: "pending",
+      rawPayload: {},
+      lastSyncedAt: 1000,
+    });
+
+    await t.mutation(internal.webhooks.markWebhookProcessed, {
+      epaycoRef: "ref_w003",
+      status: "failed",
+      errorMessage: "Invalid signature",
+    });
+
+    const event = await t.query(internal.webhooks.getWebhookEvent, {
+      epaycoRef: "ref_w003",
+    });
+    expect(event!.status).toBe("failed");
+    expect(event!.errorMessage).toBe("Invalid signature");
+  });
+});
+
+describe("verifyWebhookSignature (pure function)", () => {
+  const custIdCliente = "12345";
+  const pKey = "secretkey";
+  const refPayco = "ref_001";
+  const transactionId = "tx_001";
+  const amount = "50000";
+  const currency = "COP";
+
+  // Pinned, externally-computed SHA-256 of the canonical wire string
+  //   `${custId}^${pKey}^${ref}^${txId}^${amount}^${currency}`
+  // i.e. SHA256("12345^secretkey^ref_001^tx_001^50000^COP"). Hardcoding it
+  // (rather than recomputing with the implementation's own routine) means a
+  // regression in field order/separator would actually fail this test.
+  const KNOWN_GOOD_SIGNATURE =
+    "16514e8ce6f372b83a414bbb9141d3a09c213df702d91819f999c14e0d5b893b";
+
+  test("accepts the known-good signature", async () => {
+    const { verifyWebhookSignature } = await import("./signature.js");
+    const isValid = await verifyWebhookSignature(
+      custIdCliente,
+      pKey,
+      refPayco,
+      transactionId,
+      amount,
+      currency,
+      KNOWN_GOOD_SIGNATURE,
+    );
+    expect(isValid).toBe(true);
+  });
+
+  test("rejects a wrong signature", async () => {
+    const { verifyWebhookSignature } = await import("./signature.js");
+    const isInvalid = await verifyWebhookSignature(
+      custIdCliente,
+      pKey,
+      refPayco,
+      transactionId,
+      amount,
+      currency,
+      "wrong_signature",
+    );
+    expect(isInvalid).toBe(false);
+  });
+
+  test("rejects when a signed field is tampered", async () => {
+    const { verifyWebhookSignature } = await import("./signature.js");
+    // Same pinned signature, but a different amount must not validate.
+    const isInvalid = await verifyWebhookSignature(
+      custIdCliente,
+      pKey,
+      refPayco,
+      transactionId,
+      "99999",
+      currency,
+      KNOWN_GOOD_SIGNATURE,
+    );
+    expect(isInvalid).toBe(false);
+  });
+});

package/src/component/webhooks.ts

@@ -0,0 +1,229 @@
+import { v } from "convex/values";
+import {
+	action,
+	internalMutation,
+	internalQuery,
+} from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { verifyWebhookSignature } from "./signature.js";
+import { statusFromCodResponse } from "./status.js";
+import { rateLimiter } from "./rateLimits.js";
+
+export const processConfirmation = action({
+	args: {
+		custIdCliente: v.string(),
+		pKey: v.string(),
+		payload: v.any(),
+	},
+	handler: async (ctx, args) => {
+		const {
+			x_ref_payco,
+			x_transaction_id,
+			x_amount,
+			x_currency_code,
+			x_signature,
+			x_response,
+			x_response_reason_text,
+			x_cod_response,
+		} = args.payload;
+
+		const refPayco = String(x_ref_payco);
+
+		// Throttle per ref_payco so abuse on one reference can't starve legitimate
+		// confirmations for every other transaction.
+		await rateLimiter.limit(ctx, "webhookProcessing", {
+			key: refPayco,
+			throws: true,
+		});
+
+		// Idempotency: a fully processed confirmation is a no-op (this is a read,
+		// nothing is persisted yet).
+		const existingEvent = await ctx.runQuery(
+			internal.webhooks.getWebhookEvent,
+			{ epaycoRef: refPayco },
+		);
+
+		if (existingEvent && existingEvent.status === "processed") {
+			return { success: true, message: "Already processed" };
+		}
+
+		// Verify the signature BEFORE persisting anything, so an unauthenticated
+		// caller can never write an arbitrary payload into the table.
+		const isValid = await verifyWebhookSignature(
+			args.custIdCliente,
+			args.pKey,
+			refPayco,
+			String(x_transaction_id),
+			String(x_amount),
+			String(x_currency_code),
+			x_signature,
+		);
+
+		if (!isValid) {
+			await ctx.runMutation(internal.webhooks.storeWebhookEvent, {
+				epaycoRef: refPayco,
+				epaycoTransactionId: x_transaction_id
+					? String(x_transaction_id)
+					: undefined,
+				eventType: "confirmation",
+				status: "failed",
+				errorMessage: "Invalid signature",
+				rawPayload: { x_ref_payco: refPayco },
+				lastSyncedAt: Date.now(),
+			});
+			return { success: false, message: "Invalid signature" };
+		}
+
+		// Persist the verified event idempotently (insert-or-patch keyed by ref),
+		// so concurrent retries collapse into a single row.
+		await ctx.runMutation(internal.webhooks.storeWebhookEvent, {
+			epaycoRef: refPayco,
+			epaycoTransactionId: x_transaction_id
+				? String(x_transaction_id)
+				: undefined,
+			eventType: "confirmation",
+			status: "pending",
+			rawPayload: args.payload,
+			lastSyncedAt: Date.now(),
+		});
+
+		const codResponse = String(x_cod_response);
+		const status = statusFromCodResponse(codResponse);
+
+		const reasonText = x_response_reason_text ?? x_response;
+		const responseMessage =
+			reasonText === undefined || reasonText === null
+				? undefined
+				: String(reasonText);
+
+		const updated = await ctx.runMutation(
+			internal.transactions.updateTransactionStatus,
+			{
+				epaycoRef: refPayco,
+				status,
+				responseCode: codResponse,
+				responseMessage,
+				rawResponse: args.payload,
+			},
+		);
+
+		if (!updated) {
+			// The confirmation arrived before the local transaction row exists (an
+			// async PSE/cash/Daviplata webhook racing ahead of persistence). Park
+			// the verified event as "pending" with its payload; when the
+			// transaction row is later inserted, `transactions.upsertTransaction`
+			// drains and applies it, so the status is never lost.
+			await ctx.runMutation(internal.webhooks.markWebhookProcessed, {
+				epaycoRef: refPayco,
+				status: "pending",
+				errorMessage:
+					"Transaction not yet persisted; will reconcile on insert",
+			});
+			return { success: true, status, transactionUpdated: false };
+		}
+
+		await ctx.runMutation(internal.webhooks.markWebhookProcessed, {
+			epaycoRef: refPayco,
+			status: "processed",
+		});
+
+		return { success: true, status };
+	},
+});
+
+/**
+ * Idempotent insert-or-patch keyed by `epaycoRef`. Collapsing to one row per
+ * reference means concurrent retries (Convex serializes conflicting mutations
+ * and retries, so this is effectively atomic) can't accumulate duplicate event
+ * rows. A row already marked `processed` is never regressed.
+ */
+export const storeWebhookEvent = internalMutation({
+	args: {
+		epaycoRef: v.string(),
+		epaycoTransactionId: v.optional(v.string()),
+		eventType: v.string(),
+		status: v.union(
+			v.literal("pending"),
+			v.literal("processed"),
+			v.literal("failed"),
+		),
+		rawPayload: v.any(),
+		errorMessage: v.optional(v.string()),
+		lastSyncedAt: v.number(),
+	},
+	returns: v.id("webhookEvents"),
+	handler: async (ctx, args) => {
+		// Select the newest row for this ref, matching getWebhookEvent and
+		// markWebhookProcessed so all three operate on the same document even if
+		// legacy duplicates exist.
+		const existing = await ctx.db
+			.query("webhookEvents")
+			.withIndex("by_epaycoRef", (q) => q.eq("epaycoRef", args.epaycoRef))
+			.order("desc")
+			.first();
+
+		if (existing) {
+			if (existing.status !== "processed") {
+				await ctx.db.patch(existing._id, {
+					epaycoTransactionId:
+						args.epaycoTransactionId ?? existing.epaycoTransactionId,
+					status: args.status,
+					rawPayload: args.rawPayload,
+					errorMessage: args.errorMessage,
+					lastSyncedAt: args.lastSyncedAt,
+				});
+			}
+			return existing._id;
+		}
+
+		return await ctx.db.insert("webhookEvents", {
+			epaycoRef: args.epaycoRef,
+			epaycoTransactionId: args.epaycoTransactionId,
+			eventType: args.eventType,
+			status: args.status,
+			rawPayload: args.rawPayload,
+			errorMessage: args.errorMessage,
+			lastSyncedAt: args.lastSyncedAt,
+		});
+	},
+});
+
+export const markWebhookProcessed = internalMutation({
+	args: {
+		epaycoRef: v.string(),
+		status: v.union(
+			v.literal("pending"),
+			v.literal("processed"),
+			v.literal("failed"),
+		),
+		errorMessage: v.optional(v.string()),
+	},
+	handler: async (ctx, args) => {
+		const event = await ctx.db
+			.query("webhookEvents")
+			.withIndex("by_epaycoRef", (q) => q.eq("epaycoRef", args.epaycoRef))
+			.order("desc")
+			.first();
+
+		if (event) {
+			await ctx.db.patch(event._id, {
+				status: args.status,
+				processedAt: Date.now(),
+				errorMessage: args.errorMessage,
+				lastSyncedAt: Date.now(),
+			});
+		}
+	},
+});
+
+export const getWebhookEvent = internalQuery({
+	args: { epaycoRef: v.string() },
+	returns: v.any(),
+	handler: async (ctx, args) => {
+		return await ctx.db
+			.query("webhookEvents")
+			.withIndex("by_epaycoRef", (q) => q.eq("epaycoRef", args.epaycoRef))
+			.order("desc")
+			.first();
+	},
+});

package/src/react/index.ts

@@ -0,0 +1,71 @@
+"use client";
+
+import { useQuery, useAction } from "convex/react";
+import { useState, useCallback } from "react";
+import type { FunctionReference, FunctionArgs, FunctionReturnType } from "convex/server";
+
+type AnyQueryRef = FunctionReference<"query", "public", any, any>;
+type AnyActionRef = FunctionReference<"action", "public", any, any>;
+
+export function useTransactions<Ref extends AnyQueryRef>(
+  ref: Ref,
+  args: FunctionArgs<Ref>,
+) {
+  return useQuery(ref, args);
+}
+
+export function useTransaction<Ref extends AnyQueryRef>(
+  ref: Ref,
+  args: FunctionArgs<Ref>,
+) {
+  return useQuery(ref, args);
+}
+
+export function useSubscriptions<Ref extends AnyQueryRef>(
+  ref: Ref,
+  args: FunctionArgs<Ref>,
+) {
+  return useQuery(ref, args);
+}
+
+export function useActiveSubscription<Ref extends AnyQueryRef>(
+  ref: Ref,
+  args: FunctionArgs<Ref>,
+) {
+  return useQuery(ref, args);
+}
+
+export function useCustomer<Ref extends AnyQueryRef>(
+  ref: Ref,
+  args: FunctionArgs<Ref>,
+) {
+  return useQuery(ref, args);
+}
+
+export function usePayment<Ref extends AnyActionRef>(ref: Ref) {
+  const runAction = useAction(ref);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [result, setResult] = useState<FunctionReturnType<Ref> | null>(null);
+
+  const execute = useCallback(
+    async (args: FunctionArgs<Ref>) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const res = await runAction(args);
+        setResult(res);
+        return res;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [runAction],
+  );
+
+  return { execute, isLoading, error, result };
+}

package/src/test.ts

@@ -0,0 +1,13 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+export function register(
+	t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+	name: string = "epayco",
+) {
+	t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };