Documentación

Payezz por dentro

Cómo está montado el sistema, qué contrato tiene la API y qué parte de todo esto funciona hoy.

Cómo leer estas páginas

Payezz está en acceso anticipado. Esta documentación describe el sistema tal y como está diseñado, y marca cada pieza con su estado real para que nadie construya sobre algo que todavía no existe.

En producción
Construido, probado y en uso. Puedes integrarte contra ello.
Parcial
La estructura existe y compila, pero le falta una parte para funcionar de punta a punta.
Diseñado, sin construir
Especificado con detalle y sin una línea de código. El contrato puede cambiar antes de publicarse.

API REST

El contrato de cobros entre tu instancia y el plano de control: firma HMAC, intents, cargos, reembolsos, comisiones manuales e idempotencia.

Parcial

Webhooks

Los eventos que el plano de control reenvía firmados a tu instancia, con su política de reintentos y la regla de idempotencia que no se negocia.

Diseñado, sin construir

Servidor MCP

Conectar tu facturación a un asistente. Es lo menos avanzado de todo el producto y la página lo dice sin adornos.

Diseñado, sin construir

Módulos de aprovisionamiento

La interfaz que conecta un servicio vendido con el sistema que lo entrega: manual, Pterodactyl y los que vengan.

Diseñado, sin construir

Los dos planos

Payezz no es una aplicación con muchos inquilinos dentro de una misma base de datos. Son dos cosas distintas:

  • El plano de control da de alta instancias, guarda la clave de Stripe de la plataforma, recibe los eventos de Stripe Connect, calcula la comisión y lleva el libro de comisiones. Es lo único que ve datos de más de un cliente a la vez.
  • La instancia es el producto: la tienda, el panel del proveedor, el área de cliente, el motor de facturación y los módulos de aprovisionamiento. Cada cliente tiene la suya, con su contenedor, su base de datos y su dominio.

Lo que una instancia nunca tiene, por diseño:

  • La clave secreta de Stripe de la plataforma.
  • Acceso a la base de datos del plano de control.
  • Acceso a la base de datos de otra instancia.
  • Capacidad de decidir su propia comisión.

Los tres canales

Los dos planos se hablan por tres vías, todas autenticadas y cada una con una única dirección de iniciativa:

(A) API firmada        instancia  ──▶  plano de control
    HMAC-SHA256 + Idempotency-Key + versión de API
    cobros, intents, comisiones manuales, latido

(B) Webhooks firmados  plano de control  ──▶  instancia
    payment_intent.succeeded   charge.refunded
    payment_intent.failed      account.updated
    charge.dispute.created     plan.changed

(C) Canal de control   orquestador  ══▶  contenedor
    despliegue, migraciones, copias, suspensión,
    rotación de secretos. No pasa por la aplicación.

La instancia no tiene endpoint de Stripe. Los eventos los recibe el plano de control en un único punto, resolviendo la cuenta conectada por el campo account del evento, los traduce a eventos de dominio de Payezz y los reenvía firmados. Así hay un solo secreto de webhook en todo el sistema, las instancias no necesitan ser alcanzables desde fuera y la política de reintento es nuestra.

El canal de control no pasa por la aplicación: habla con el motor de contenedores y con el DNS. Una instancia no tiene forma de invocarlo, y eso es lo que impide que un fallo en el código de la tienda toque la infraestructura.

Convenciones que valen para todo

  • El dinero va en enteros de la unidad mínima. 1499 son 14,99 euros. Nunca decimales, nunca coma flotante. Un campo que lleva importe se llama amount_minor, no amount, para que nadie se confunda al leerlo.
  • La moneda va en ISO 4217 en minúsculas: eur, usd.
  • Las fechas van en ISO 8601 con zona horaria, en UTC.
  • Los porcentajes de comisión viajan en puntos básicos enteros: 190 es 1,9 %. Así no hay redondeos a mitad de camino.
  • Toda petición lleva versión de API. Una instancia que no se ha actualizado tiene que seguir funcionando.

Qué funciona hoy

Con nombre y apellidos, para que nadie planifique sobre humo. Están construidos y probados el motor de comisión, la autenticación entre la instancia y el plano de control y los dos esquemas de base de datos. La pasarela de cobros está montada y le faltan sus consultas a base de datos, así que hoy responde con error. El editor de la tienda, el panel de SEO, el servidor MCP y los módulos de aprovisionamiento están especificados y sin construir.

Si vas a integrarte y necesitas saber cuándo estará algo concreto, escríbenos a hola@payezz.app y te decimos la fecha que manejamos, sin inflarla.