En esta página

Pagos de Agentes IA (x402)

iion pay 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.

Todavía no disponible
x402 todavía no está activo para los comercios. Avísanos si lo quieres usar.
¿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 comercio debe tener X402 habilitado; si no, el API lo quita de allowedMethods.

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 de iion pay. 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: iion pay ejecuta la transferencia on-chain.

Recibes tu liquidación normal

Verificado el pago on-chain, la orden pasa a COMPLETED y llega tu webhook payment.completed de siempre. El agente paga el amount de la orden. La comisión sigue el feeMode de la orden, igual que con PSE o tarjeta: con MERCHANT_PAYS se descuenta de lo que recibes; con CUSTOMER_PAYS el agente la paga encima del baseAmount y tú recibes el baseAmount completo. Tú nunca tocas cripto.

1. Crear una orden pagable por agentes

POST /v1/collect
curl -X POST https://api.prod.iionpay.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.iionpay.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 iion pay.

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: iion pay ejecuta la transacción.

Errores comunes

Error (en el body 402)Significado
method_not_allowedLa orden no incluye X402 en allowedMethods.
order_already_paidLa orden ya fue pagada (por otro agente u otro método).
order_expiredLa orden venció antes del pago.
insufficient_amountEl valor autorizado no cubre la cotización vigente. Pedir un 402 fresco y firmar el monto exacto.
replayNonce ya usado. Firmar con un nonce nuevo.
quote_unavailableSin tasa de cambio confiable en este momento. Reintentar en unos minutos.
escrow_not_supportedLas ó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.