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.
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?
Igual que cualquier orden de cobro, incluyendo "X402" en allowedMethods. Tu comercio debe tener X402 habilitado; si no, el API lo quita de allowedMethods.
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.
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.
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
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
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.
{
"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" }
}
]
}
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"
}
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_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. |
maxTimeoutSeconds en pagar, debe pedir un 402 nuevo — la firma sobre una cotización vencida es rechazada.