feat(payment): expose secure APIs and themed pages

packages/payment/README.md

@@ -29,3 +29,56 @@ const payment = {
 ```
 
 At runtime, call `configurePaymentFromConfig(config.payment, databasePaymentStore())` once. Pass a configured gateway name to `initializePayment` to override the default for a specific checkout.
+
+## Package APIs
+
+When a modern `gateways` configuration is present, the plugin contributes these routes:
+
+- `GET /api/payments/providers` — client-safe names, capabilities, currencies, and countries
+- `GET|POST /api/payments/intents` — list the authenticated subject's payments or initialize one
+- `GET /api/payments/intents/[id]` — status and client-safe checkout configuration
+- `POST /api/payments/intents/[id]/sync`
+- `POST /api/payments/intents/[id]/capture`
+- `POST /api/payments/intents/[id]/cancel`
+- `POST /api/payments/intents/[id]/refund`
+- `GET /api/payments/methods`
+- `POST /api/payments/reconcile`
+- `POST /api/payments/webhook/:gateway`
+
+Provider secrets are held only by server adapters and are never returned by provider, intent, or status APIs. Request-body subject values are ignored. Configure authentication and authorization in the same payment block:
+
+```ts
+payment: {
+  default: "razorpayIndia",
+  gateways: { /* named providers */ },
+  api: {
+    subject: (ctx) => ctx.session?.userId,
+    authorize: async (ctx, action, payment) => {
+      if (["capture", "refund", "reconcile"].includes(action))
+        return await isBillingAdmin(ctx)
+      return !payment || payment.subject === ctx.session?.userId
+    },
+    // Recommended for catalog purchases: derive price and metadata server-side.
+    initialize: async (ctx, body, subject) => resolveCatalogPurchase(body, subject),
+  },
+}
+```
+
+Administrative actions deny by default. Set `api: false` to expose only the signed webhook endpoint. Use CSRF protection and rate limiting in the application's normal middleware.
+
+## Pages, themes, and languages
+
+The package exposes `PaymentOverviewPage`, `PaymentDetailsPage`, `PaymentCheckoutPage`, and `PaymentMethodsPage`, plus the smaller payment components. These use framework theme variables, inherit light/dark mode and accent colors, and collapse to a single-column mobile layout.
+
+All visible copy is supplied through component props. Applications can pass their normal i18n messages without the package forcing a locale or duplicating the application's language switcher:
+
+```wrn
+<PaymentMethodsPage
+  methods={payments.methods}
+  title={t.paymentMethodsTitle}
+  description={t.paymentMethodsDescription}
+  emptyLabel={t.noPaymentMethods}
+/>
+```
+
+Provider-hosted card fields remain on the provider's origin. Applications should never collect or pass raw card numbers, CVVs, or expiry values through these APIs.