Convex Payment Methods

@primocaredentgroup/payment-methods-management is the Convex component that owns payment methods, credit-note compatibility, payment resources, loan institutes, payment modalities and POS configuration.

Installation

npm install @primocaredentgroup/payment-methods-management

Mount the component once in the consuming application's convex.config.ts:

import { defineApp } from "convex/server";
import paymentMethods from "@primocaredentgroup/payment-methods-management/convex.config.js";

const app = defineApp();
app.use(paymentMethods);
export default app;

Typed host boundary

Use exposeApi to publish only authenticated and authorized host functions:

import { components } from "./_generated/api";
import { exposeApi } from "@primocaredentgroup/payment-methods-management";

export const {
  getActivePaymentMethods,
  createPaymentMethod,
  createModalityPayment,
} = exposeApi(components.paymentMethods, {
  auth: async (ctx, operation) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthorized");
    if (operation.type === "write") {
      // Enforce host-owned RBAC here.
    }
  },
});

Backend orchestration can use PaymentMethodsClient directly. Public argument and response validators are available from the package root and from the ./validators subpath.

Canonical contracts

• payment modality type is one_only | more_rows;
• posSettings.clinicId is an external string identifier;
• timestamps are numeric milliseconds after migration;
• optional fields are omitted instead of stored as explicit null;
• payment documents should retain a snapshot of the selected payment method's external id and display name.

Satispay ownership

The component owns non-secret payment-method and payment-resource metadata. Satispay activation codes, tokens and API credentials remain in the consuming host's integration layer and must be stored as protected secrets. They are not part of this component's public contract.

Legacy migration

Version 0.3.x is the widening release for existing installations. After the component has been installed on a development or production deployment, run:

npx convex run --component paymentMethods migrations:normalizeLegacyData '{"dryRun":true}'
npx convex run --component paymentMethods migrations:normalizeLegacyData
npx convex run --component paymentMethods migrations:verifyLegacyData

Run production migrations only after an explicit rollout approval and verify that complete is true before installing the 0.4.x narrowing release. Version 0.4.x no longer exposes the migration functions and rejects legacy timestamps, explicit null optionals, numeric POS clinic ids and free-form payment modality types.

Development

npm ci
npm run verify
npm pack --dry-run