Core · Service · Active

platform-payments-service

Provider-agnostic CORE payment boundary for pricing catalog, checkout sessions, Stripe webhooks, purchase and subscription records, and normalized payment events to product backends.

• TypeScript
• NestJS 11
• Prisma
• PostgreSQL
• Stripe SDK
• @platform/contracts-payments

Spec sheet

Boundary

Core / Payments

Runtime

NestJS 11 HTTP service

Default port

3700

Proxy host

http://payments.cs.lvh.me:8080

Persistence

Dedicated payments-postgres via PAYMENTS_DATABASE_URL

Security

Internal routes guarded by x-platform-internal-token; provider webhook is public and signature-validated

Primary provider

Stripe

Responsibilities

• Keep provider-specific payment SDK logic out of product BFFs.
• Own the shared pricing item catalog and provider price references.
• Create provider checkout sessions for product backends.
• Ingest provider webhooks and persist purchase, subscription and event state.
• Deliver normalized payment events back to product consumers such as FunnelAI.
• Expose plan, checkout and payment record lookup APIs for backend-to-backend consumers.

Interfaces and contract surface

• GET /health
• GET /internal/payments/providers
• GET /internal/payments/pricing-items
• GET /internal/payments/public/pricing-items
• POST /internal/payments/pricing-items
• PATCH /internal/payments/pricing-items/:id
• DELETE /internal/payments/pricing-items/:id
• POST /internal/payments/checkout-sessions
• GET /internal/payments/checkout-sessions/:providerCheckoutSessionId
• GET /internal/payments/tenants/:consumerTenantId/plan-status
• GET /internal/payments/purchases
• GET /internal/payments/subscriptions
• POST /internal/payments/event-deliveries/:id/retry
• POST /webhooks/stripe

Consumers

• funnel backend
• cs transaction api
• platform-status-service health monitoring

Dependencies and external touchpoints

• platform-local-stack
• @platform/contracts-payments
• Payments Postgres
• Stripe

Notes

• Frontend applications must not call this service directly; products expose their own BFF/facade.
• CS Transaction Manage reads tenant plan status here to compute subscription-aware product capabilities.
• The FunnelAI rollout includes a one-time import:funnel-billing backfill before legacy billing tables are removed.
• PAYMENTS_CONSUMER_FUNNEL_EVENTS_URL points normalized payment events to the FunnelAI backend in the local stack.

Source references

• platform-payments-service/README.md
• docs/core-services-integration.md
• platform-payments-service/prisma/schema.prisma
• platform-payments-service/package.json

Come integrarsi davvero

platform-payments-service e il boundary CORE per pagamenti provider-agnostic. I frontend non lo chiamano direttamente: i prodotti espongono una BFF/facade e usano questo servizio solo backend-to-backend.

Variabili utili

export PAYMENTS_URL=http://127.0.0.1:3700
export INTERNAL_TOKEN=platform-local-stack-internal-token

Provider e catalogo

curl -sS "$PAYMENTS_URL/internal/payments/providers" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"

curl -sS "$PAYMENTS_URL/internal/payments/public/pricing-items?active=true" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"

Checkout

Il backend prodotto crea o risolve il proprio tenant locale, poi chiede al payment service una checkout session.

curl -sS -X POST "$PAYMENTS_URL/internal/payments/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "providerKey": "stripe",
    "pricingItemCode": "starter_month",
    "consumerKey": "funnel",
    "consumerTenantId": "tenant_123",
    "tenantName": "Demo",
    "legalName": "Demo SRL",
    "billingEmail": "billing@example.test",
    "successUrl": "http://funnel.cs.lvh.me:8080/#/pricing/complete?session_id={CHECKOUT_SESSION_ID}",
    "cancelUrl": "http://funnel.cs.lvh.me:8080/#/pricing?checkout=cancel"
  }'

Webhook provider

Stripe deve puntare a:

POST /webhooks/stripe

Il servizio salva l'evento provider, aggiorna purchase/subscription nel proprio database e invia eventi normalizzati al consumer configurato, ad esempio POST /api/internal/payments/events di FunnelAI.