Pagos de Agentes IA (x402)

NIIO Payments es compatible con el protocolo x402: cualquier agente de inteligencia artificial puede pagar tus órdenes de cobro de forma autónoma — sin cuenta, sin tarjeta y sin OAuth. El agente paga en USDC (Polygon) y tú recibes tu liquidación normal, igual que con PSE o tarjeta.

¿Qué es x402?

x402 (x402.org) es un estándar abierto de pagos máquina-a-máquina sobre HTTP, impulsado por Coinbase, Cloudflare y Google. Usa el código de estado 402 Payment Required: el servidor publica cuánto y dónde pagar, el agente adjunta una autorización firmada criptográficamente y el pago se liquida on-chain en segundos.

¿Cómo funciona?

Crea la orden con el método X402

Igual que cualquier orden de cobro, incluyendo "X402" en allowedMethods. Tu API key debe tener el método habilitado.

El agente consulta el endpoint de pago

Recibe un 402 Payment Required con los requisitos: monto exacto en USDC, red, y la dirección de tesorería NIIO. La cotización COP→USDC es fija por 5 minutos.

El agente firma y paga

Firma una autorización EIP-3009 (transferWithAuthorization) con su wallet y reintenta la petición con el header X-PAYMENT. No necesita gas: NIIO ejecuta la transferencia on-chain.

Recibes tu liquidación normal

Verificado el pago on-chain, la orden pasa a COMPLETED, recibes tu monto base completo (el fee lo paga el agente on-top) y llega tu webhook payment.completed de siempre. Tú nunca tocas cripto.

1. Crear una orden pagable por agentes

POST /v1/collect

curl -X POST https://api.prod.niiopay.com/api/v1/collect \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -d '{
    "amount": 50000,
    "currency": "COP",
    "reference": "orden-1234",
    "description": "Suscripción mensual",
    "allowedMethods": ["X402"]
  }'

Puedes combinar métodos (["PSE", "CARD", "X402"]): humanos pagan por el checkout web y agentes por el endpoint x402 — el primero que pague gana, sin dobles cobros.

2. El endpoint de pago x402

GET /v1/x402/collect/{orderId}/pay

Endpoint público (también acepta POST). Sin header X-PAYMENT responde 402 con los requisitos de pago; con el header, verifica la firma, liquida on-chain y responde 200.

Respuesta 402 — requisitos de pago (x402 v2)

{
  "x402Version": 2,
  "error": "X-PAYMENT header is required",
  "resource": {
    "url": "https://api.prod.niiopay.com/api/v1/x402/collect/{orderId}/pay",
    "description": "Suscripción mensual",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:137",
      "asset": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      "amount": "15340000",
      "payTo": "0x...",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

Respuesta 200 — pago liquidado

HTTP/1.1 200 OK
X-PAYMENT-RESPONSE: <base64 con el resultado del settlement>

{
  "success": true,
  "orderId": "...",
  "reference": "orden-1234",
  "status": "COMPLETED",
  "txHash": "0x...",
  "network": "eip155:137"
}

Idempotente por diseño

Si el agente reintenta con la misma autorización firmada, recibe el mismo txHash — nunca hay doble cobro. El nonce EIP-3009 se quema on-chain y se registra en NIIO.

Compatibilidad con agentes

Funciona con cualquier cliente x402 v2 estándar: x402-fetch, @x402/axios, frameworks de agentes (LangGraph, OpenAI Agents SDK, AWS Bedrock AgentCore) o una integración propia. El agente solo necesita una wallet EVM con USDC nativo en Polygon — no necesita MATIC/POL para gas: NIIO ejecuta la transacción.

Errores comunes

Error (en el body 402)	Significado
`method_not_allowed`	La orden no incluye `X402` en `allowedMethods`.
`order_already_paid`	La orden ya fue pagada (por otro agente u otro método).
`order_expired`	La orden venció antes del pago.
`insufficient_amount`	El valor autorizado no cubre la cotización vigente. Pedir un 402 fresco y firmar el monto exacto.
`replay`	Nonce ya usado. Firmar con un nonce nuevo.
`quote_unavailable`	Sin tasa de cambio confiable en este momento. Reintentar en unos minutos.
`escrow_not_supported`	Las órdenes con custodia (escrow) no aceptan x402 por ahora.

La cotización expira en 5 minutos

El monto en USDC incluye la tasa COP→USD del momento. Si el agente tarda más de maxTimeoutSeconds en pagar, debe pedir un 402 nuevo — la firma sobre una cotización vencida es rechazada.