Cobrar por una API, un dataset, una página premium o una herramienta MCP no obliga a convertir cada recurso en un checkout tradicional. Con x402, el intercambio HTTP puede indicar que se requiere un pago, describir las opciones aceptadas y permitir que un cliente compatible autorice el acceso. La dificultad real consiste en diseñar reglas, verificación, ejecución, liquidación, medición y conciliación sin exponer el origen.
Esta guía explica la documentación de x402 de Cloudflare (se abre en una pestaña nueva ↗) y un Monetization Gateway interoperable con x402 usando como referencia el anuncio de Cloudflare y la documentación actual del protocolo. No afirma que todas las capacidades estén disponibles para cualquier cuenta de AZPay o Cloudflare. Hay que confirmar disponibilidad, red, activo, facilitador y condiciones comerciales en el entorno elegido.
Qué resuelve x402
HTTP ya tiene el estado 402 Payment Required, pero por sí solo no define cómo comunicar precio, red, activo, destinatario o autorización. x402 añade objetos y cabeceras para que el servidor describa los requisitos y el cliente devuelva una autorización firmada. En la versión 2, la respuesta usa PAYMENT-REQUIRED y la solicitud pagada usa PAYMENT-SIGNATURE.
El flujo es: solicitud, requisitos 402, repetición firmada, verificación, ejecución según el esquema, liquidación y entrega. Es útil para API y agentes, pero no convierte cualquier navegador en una wallet ni elimina las responsabilidades de identidad, autorización, seguridad del origen y soporte.
Una capa de control, no solo un paywall
El gateway debe saber qué recurso se solicita, quién puede acceder, cuánto cuesta, cómo se verifica el pago y qué sucede después. Las reglas pueden combinar dominio, ruta, método HTTP, audiencia, cabeceras, parámetros y atributos del llamador.
El plano de control debe conservar recursos, orígenes, reglas versionadas, wallets receptoras, redes, entornos y auditoría. El plano de datos evalúa reglas en el edge, devuelve 402 cuando corresponde, protege el origen y registra el ciclo. Publicar políticas sin redeplegar cada aplicación exige snapshots versionados, precedencia explícita y rollback.
exact y upto
Con exact, el importe autorizado debe coincidir con el precio exigido. Con upto, el cliente autoriza un máximo y el servidor puede informar del consumo real cuando la implementación y el facilitador lo permitan. El precio variable exige medición confiable: un máximo no es permiso para cobrar cualquier cantidad.
No confundas precio por solicitud con suscripciones, saldo prepago o facturación posterior. Registra intención, autorización, verificación, ejecución, valor medido, liquidación, respuesta entregada y error como hechos relacionados.
El origen sigue dentro de la seguridad
Verificar en el edge no permite saltarse el origen. Impide el acceso directo, conserva el contexto necesario y, cuando corresponda, envía un contexto firmado que el origen pueda validar. Las cabeceras x402 para el cliente y las cabeceras de confianza entre gateway y origen son superficies distintas.
Convertir un 401 del origen en una oportunidad de pago debe ser una política explícita. Un usuario autenticado no debería perder su sesión por un error de reglas, y un comprador no autenticado no debería obtener acceso porque todos los errores se transformaron en 402.
Facilitadores, redes y entornos
Un facilitador expone operaciones de verificación y liquidación para un esquema y una red compatibles. Sus activos, firmantes, límites, expiración, costes y responsabilidades varían. Usa testnet para validar el contrato técnico y separa desarrollo, testnet y producción.
x402 v2 usa identificadores de red CAIP-2 y campos como scheme, network, asset, amount, payTo y maxTimeoutSeconds. Utiliza bibliotecas compatibles y consulta las capacidades del facilitador antes de publicar una regla.
Dónde encaja Pix
Pix y x402 están relacionados, pero no son el mismo protocolo. Pix es el sistema de pagos brasileño con su propio ciclo de cobro, QR, confirmación y conciliación. x402 es una convención de pago dentro de HTTP, con esquemas y redes definidos por la implementación. Una empresa puede atender a clientes x402 y mantener un checkout Pix separado; un QR no es una firma x402 y una wallet x402 no es automáticamente una cuenta Pix.
En Pix, la confirmación fiable procede del participante y de la integración contratada, no de la pantalla del cliente. Consulta la guía de AZPay sobre el ciclo de Pix.
Checklist antes de publicar
Empieza por la propiedad del recurso y comprueba que el origen no sea accesible fuera del gateway. Define la precedencia, el cálculo de exact o upto, la versión del protocolo, la red, el activo, la wallet, el facilitador y el entorno.
Prueba acceso sin pago, autorización válida, expiración, importe incorrecto, nonce repetido, fallo de liquidación, timeout y reintento seguro. Concilia intento de acceso, autorización, liquidación on-chain y recurso entregado mediante identificadores estables.
Preguntas frecuentes
¿x402 sustituye un checkout humano? No. Es especialmente útil para clientes programáticos, agentes y aplicaciones que pueden interpretar requisitos y firmar autorizaciones. Un checkout humano puede necesitar accesibilidad, autenticación y medios locales como Pix.
¿El anuncio demuestra que el producto está disponible? No. La documentación actual, el acceso de la cuenta, la red, el facilitador y los contratos aplicables determinan qué se puede activar. Trata las capacidades no probadas como no confirmadas.
La primera entrega útil es una regla comprobable, un origen protegido, un cliente compatible, un entorno separado y un registro auditable. El objetivo es construir una frontera verificable entre intención, pago y acceso.