Entrevista de Backend: ¿Cómo diseñarías una API de pago por solicitud con HTTP 402/x402?

Pregunta

Necesitas agregar acceso de pago por solicitud a una API de datos. Una solicitud no pagada debe devolver HTTP 402, y el cliente debe reintentar la solicitud original después de pagar. Explica el estado de 402 en RFC 9110 y diseña un protocolo de extremo a extremo tipo x402 que cubra requisitos de pago, verificación de pruebas, vinculación de recursos, protección contra repetición, idempotencia, reembolsos y conciliación.

Qué está evaluando el entrevistador

• Si distingues el significado estandarizado de 402 de un esquema de pago concreto: RFC 9110 reserva el código de estado pero no define una red de pago, moneda o formato de respuesta.
• Si vinculas la prueba de pago al recurso, monto, destinatario, red y expiración para que un pago no pueda trasladarse a otra solicitud.
• Si manejas reintentos de clientes, tiempos de espera, cobros duplicados, retrasos en la confirmación de la cadena de bloques y consistencia contable.
• Si puedes establecer los límites de confianza entre el servicio de pago, el servicio de recursos, la parte de liquidación y el registro de auditoría.

Respuesta modelo

402 está registrado como "Payment Required" en el registro de códigos de estado HTTP. RFC 9110 lo reserva pero no define un protocolo de pago universal. Un protocolo debe tratar a 402 como un desafío legible por máquina, no como una prueba de que el pago ya se ha realizado.

El servicio de recursos puede devolver un requisito de pago único en la respuesta 402. Debe incluir un identificador de recurso, método y ruta, monto, activo, red, destinatario, expiración y nonce. El cliente firma o paga exactamente por esos campos. El servicio o un facilitador de confianza verifica la prueba, comprueba el monto, destinatario, red y recurso, y luego entrega al servicio de recursos un recibo de un solo uso.

El servicio de recursos debe registrar la relación idempotente entre un ID de solicitud y un ID de pago antes de ejecutar una operación costosa. Un reintento con el mismo ID de solicitud devuelve el mismo resultado o un estado de procesamiento explícito. Un pago exitoso no implica una ejecución exitosa del recurso, por lo que el pago, la autorización, la ejecución y el reembolso necesitan estados rastreables. Un trabajo de conciliación debe encontrar diferencias entre la confirmación en cadena, los registros del servicio y la entrega real.

Esquema de implementación

El pseudocódigo a continuación muestra el desafío central y los límites de reintento; un sistema en producción también necesita un verificador de pagos, almacenamiento idempotente y registro de auditoría.

handle(request):
  id = request.idempotencyKey
  if receiptStore.has(id):
    return receiptStore.result(id)

  requirement = makeRequirement(
    resource = canonicalResource(request),
    amount = quote(request),
    network = "base",
    expiresAt = now + 60s,
    nonce = randomBytes(16)
  )

  proof = request.headers["Payment-Proof"]
  if proof is missing:
    return 402, { "payment-required": requirement }

  payment = verifyProof(proof, requirement)
  if payment.invalid or payment.expired or payment.replayed:
    return 402, { "payment-required": requirement, "reason": "invalid-proof" }

  result = executeOnce(id, request, payment)
  receiptStore.put(id, payment.id, result)
  return 200, result

El invariante clave es que canonicalResource y verifyProof utilicen las mismas reglas de normalización. De lo contrario, un recurso puede tener múltiples representaciones de cadena y la verificación de la firma puede no coincidir con la autorización. executeOnce necesita una restricción única, transacción o estado duradero para que un reintento no pueda duplicar efectos secundarios.

Errores comunes

• Asumir que 402 incluye un flujo de pago. Solo indica que se requiere el pago; el protocolo debe definir los campos y las reglas de verificación.
• Verificar únicamente el monto mientras se ignora el recurso, la red, el destinatario, el activo o la expiración, lo que permite la sustitución entre recursos o la repetición entre redes.
• Ejecutar efectos secundarios inmediatamente después de la confirmación del pago sin un registro de solicitud idempotente, por lo que un reintento por tiempo de espera cobra o crea el recurso dos veces.
• Tratar una transacción de cadena enviada como una liquidación final; el retraso de confirmación, las reorganizaciones, las fallas de facilitadores y los reembolsos pertenecen a la máquina de estados.
• Colocar pruebas de pago en registros o URLs, generando fuga de credenciales y riesgo de repetición.

Compensaciones en producción

Para lecturas de bajo valor y bajo riesgo, una cotización de corta duración, un nonce de un solo uso y una conciliación final asíncrona pueden ser aceptables. Las escrituras de alto valor deben obtener un estado de liquidación verificable antes de la entrega y ejecutarse detrás de una transacción idempotente. Si los clientes no tienen billetera o capacidades on-chain, un facilitador puede pagar en su nombre, pero su alcance de confianza, tarifas, límites y respaldo ante fallas deben ser explícitos.

El protocolo también necesita reglas para cambios de precio, desafíos expirados, pagos parciales, pago exitoso seguido de falla del recurso, reembolsos y degradación del servicio. Una caché no debe compartir una respuesta que contenga una prueba de pago con otra entidad; su clave debe incluir el resultado de la autorización, o solo debe almacenar en caché el desafío 402 público.

Referencias

• RFC 9110 HTTP Semantics: semántica de registro de 402 y restricciones de estado HTTP.
• x402 Introduction: concepto del protocolo de pago por solicitud sin cuenta, impulsado por desafíos.
• Coinbase HTTP 402 Core Concepts: límites de implementación para requisitos de pago, verificación y acceso a recursos.

Preguntas de seguimiento

¿Cómo evitas que una misma prueba de pago se use para dos recursos?

Coloca el método normalizado, la ruta, el resumen de consulta (query digest) o el ID de recurso en el requisito de pago y cubre esos campos con la prueba. El servicio vuelve a calcular el resumen con el mismo algoritmo de normalización y registra cada nonce o ID de pago como de un solo uso.

¿El desafío 402 debe estar en los encabezados o en el cuerpo de la respuesta?

Define primero un formato versionado legible por máquina. Los encabezados se adaptan bien a una sugerencia pequeña, mientras que el cuerpo puede transportar un requisito de pago de múltiples campos. De cualquier manera, limita su tamaño, declara su tipo de contenido y evita colocar credenciales sensibles en encabezados almacenables en caché.

¿Qué pasa si el pago tiene éxito pero la ejecución de negocio falla?

Mantén el pago, la autorización, la ejecución y el reembolso como estados separados vinculados por el ID de solicitud. Si la operación no es reintentable, entra en una cola de reembolso o conciliación manual. Si es reintentable, devuelve un estado de procesamiento y haz que las lecturas posteriores devuelvan el mismo resultado.

¿Requiere x402 una cadena de bloques?

El material actual de x402 utiliza pagos on-chain o facilitadores como ejemplos, pero HTTP 402 en sí mismo no prescribe una red de liquidación. Separa la semántica del código de estado del riel de pago; cambiar el riel requiere redefinir la prueba, la finalidad y la semántica de reembolso.

¿Cómo verificas que el sistema nunca cobre el doble?

Agrega restricciones únicas para el ID de pago, ID de solicitud y la operación de negocio; registra cada resultado de verificación y ejecución; e inyecta fallas que cubran tiempos de espera de clientes, reinicios de servicios, devoluciones de llamada de verificador duplicadas y conciliaciones demoradas.