# iion pay — Cobros (Payin) y Dispersiones (Payout) (referencia completa para LLMs) > Todo lo necesario para integrar cobros con iion pay desde tu backend, sin seguir > enlaces externos. API de cobros para comercios en Colombia: PSE, Nequi, > Daviplata, Bancolombia, Efecty y tarjeta. > > Base URL: https://api.prod.iionpay.com/api/v1 > Checkout hosted: https://pay.iionpay.com/c/:id > Contacto: soporte@iionpay.com ## Conceptos - **Merchant:** tu comercio en iion pay. Tiene API keys y configuración de webhook. - **Collect order:** una orden de cobro. Tú la creas; tu cliente la paga. - **Comisión:** la define el plan o el contrato de tu comercio. Quién la asume lo indica `feeMode`. Ver «Modelo de monto». - **Pay-gateway:** el checkout hosted (`pay.iionpay.com/c/:id`) donde tu cliente paga. No implementas UI de pago. **Modelo de monto (importante):** - Pides `amount`: es el valor del cobro (el `baseAmount`). - Quién asume la comisión lo indica `feeMode`: - `MERCHANT_PAYS`: el pagador paga `baseAmount`. La comisión (`feeAmount`) se descuenta de lo que recibes. - `CUSTOMER_PAYS`: el pagador paga `baseAmount + feeAmount`. Tú recibes `baseAmount`. El total depende del método de pago que elige el pagador (ver «Total según el método de pago»). - El modo de cada cobro sale en este orden: el contrato de tarifa de tu comercio (si fija un modo, manda), el campo `feeMode` del cobro y, sin campo, el modo por defecto de tu comercio. No hay un modo por defecto igual para todos: lee siempre `feeMode` en la respuesta. - El porcentaje de la comisión lo define el plan o el contrato de tu comercio. - La respuesta trae siempre el desglose: `amount` (paga el pagador), `baseAmount`, `feeAmount` y `feeMode`. - Con `CUSTOMER_PAYS`, el `amount` de la respuesta puede cambiar cuando el pagador elige el método. El total final llega en el webhook `payment.completed`. ## Autenticación Todas las llamadas de cobro requieren dos headers: ``` X-Api-Key: niio_live_... X-Api-Secret: niio_secret_... ``` Las credenciales se crean y revocan en el panel de negocios, en Integraciones → API keys. Las API keys autentican las llamadas de cobro. El `webhookSecret` (distinto) valida los webhooks entrantes. ## Si eres un agente de IA: pasos en orden Sigue estos pasos en este orden. 1. Guarda la llave y el secreto en variables de entorno: `IIONPAY_API_KEY` e `IIONPAY_API_SECRET`. Nunca los escribas en el código ni en el repositorio. 2. Implementa tres piezas: crear la orden (§1), redirigir al pagador (§2) y un handler de webhook (§3). El handler verifica la firma y es idempotente. 3. Obtén una URL pública para el handler. Usa el deploy del comercio. En local, usa ngrok o localtunnel. 4. Llama a `PUT /api/v1/collect/webhook` con esa URL (ver «Registrar tu webhook por API»). Guarda el `whsec_` de la respuesta como `IIONPAY_WEBHOOK_SECRET`. 5. Llama a `POST /api/v1/collect/webhook/test`. Confirma que tu handler recibe el aviso y que la firma es válida. 6. Crea una orden de prueba por 5.000 COP. Si recibes `400 COLLECT_AMOUNT_BELOW_MINIMUM`, el `message` trae el mínimo vigente: crea la orden de nuevo con ese monto. Consúltala con `GET /api/v1/collect/:id`. Muestra el `collectUrl` al usuario. 7. Si recibes `403 KYC_OR_KYB_REQUIRED` al crear la orden, dile al usuario que verifique su negocio en el panel, sección Verificación. Si recibes `403 FEATURE_DISABLED` al registrar el webhook, pídele al usuario que configure el webhook general del comercio en el panel: Integraciones → Webhooks («Webhook general»). Pídele también que copie ahí la «Clave del webhook» y te la dé para guardarla como `IIONPAY_WEBHOOK_SECRET`. ## 1. Crear una orden de cobro ``` POST https://api.prod.iionpay.com/api/v1/collect X-Api-Key: niio_live_... X-Api-Secret: niio_secret_... Content-Type: application/json ``` **Body** (campos `customer*` son opcionales — el checkout los pide si faltan): ```json { "amount": 150000, "currency": "COP", "reference": "wc-order-1042", "description": "Pedido #1042", "customerName": "Juan Pérez", "customerEmail": "juan@example.com", "customerDocType": "CC", "customerDocNumber": "1234567890", "allowedMethods": ["PSE", "BANK_TRANSFER", "CARD"], "feeMode": "CUSTOMER_PAYS", "callbackUrl": "https://mitienda.com/return?order=1042", "metadata": { "wooOrderId": 1042 }, "expirationMinutes": 60 } ``` | Campo | Req. | Notas | |-------|------|-------| | `amount` | sí | Valor del cobro (COP, entero). Según `feeMode`, la comisión se descuenta de lo que recibes o la paga el pagador encima. Hay un monto mínimo por cobro en COP (ver «Monto mínimo»). | | `reference` | sí | Tu ID único de la orden (idempotencia). | | `currency` | no | Default `COP`. | | `customerDocType` | no | `CC`, `CE`, `NIT`, `PP`. | | `allowedMethods` | no | Sin el campo, el cobro usa los métodos habilitados para tu comercio (un comercio nuevo nace con `["PSE","BANK_TRANSFER"]`). Valores: `PSE`, `BANK_TRANSFER`, `ACH`, `WIRE`, `CRYPTO`, `CARD`, `X402`. iion pay quita los que tu comercio no tiene habilitados; si no queda ninguno, responde `400`. La respuesta trae la lista final. | | `feeMode` | no | `CUSTOMER_PAYS` o `MERCHANT_PAYS`: quién asume la comisión en este cobro. Sin el campo, el modo por defecto de tu comercio. Un contrato de tarifa con modo propio manda sobre el campo. Si `MERCHANT_PAYS` no está disponible, responde `400 FEE_MODE_UNAVAILABLE`. | | `callbackUrl` | no | A dónde vuelve el pagador tras pagar (solo UX; ver §4). | | `metadata` | no | JSON arbitrario; se devuelve en el webhook. | | `expirationMinutes` | no | Default 60. | ### Monto mínimo - Cada cobro en COP tiene un monto mínimo. iion pay lo fija y lo puede cambiar. - El mínimo se compara con la base del cobro: el monto sin comisión y, si hay cupón, con el descuento ya aplicado. - Bajo el mínimo, la API responde `400` con `code` `COLLECT_AMOUNT_BELOW_MINIMUM`. El `message` trae el mínimo vigente, por ejemplo «El monto mínimo de un cobro es $5.000 COP». - Con `MERCHANT_PAYS`, la comisión y su impuesto deben ser menores que el monto. Si no, la API responde `400`. **Respuesta `201`:** ```json { "success": true, "data": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "reference": "wc-order-1042", "amount": 151235, "baseAmount": 150000, "feeAmount": 1235, "currency": "COP", "status": "PENDING", "collectUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479", "expiresAt": "2026-06-25T15:30:00.000Z", "createdAt": "2026-06-25T14:30:00.000Z" } } ``` Ejemplo con `feeMode` `CUSTOMER_PAYS` (Bre-B, plan START): `amount` (151235) es lo que paga el pagador al crear el cobro y `baseAmount` (150000) es lo que recibes. Con `MERCHANT_PAYS`, `amount` es igual a `baseAmount` y recibes `baseAmount` − `feeAmount`. En órdenes antiguas `baseAmount`/`feeAmount` pueden ser `null`. La respuesta de crear trae también estos campos: | Campo | Significado | |-------|-------------| | `feeMode` | Quién asume la comisión en este cobro: `CUSTOMER_PAYS` o `MERCHANT_PAYS`. | | `taxAmount` | Impuesto sobre la comisión de iion pay. `null` en órdenes creadas sin el motor de tarifas. | | `netAmount` | Lo que se acredita a tu comercio por el cobro. `null` en órdenes creadas sin el motor de tarifas: ahí se acredita `baseAmount`. | | `providerFeeAmount` | Comisión del proveedor de pago que asume tu comercio (por ejemplo, en ventas de datáfono). Solo baja lo que recibes; no es parte de `feeAmount`. `null` si no hay. | | `withholdingAmount` | Retenciones de ley que aplicó el proveedor de pago. `null` si no hay. | | `providerName` | Proveedor de pago que registró esa comisión. `null` si no hay. | | `couponCode` | Código del cupón aplicado al cobro. `null` sin cupón. | | `discountAmount` | Descuento del cupón. `null` sin cupón. | | `branchId` | Sede del cobro. `null` = sin sede. | | `deliveryUrl` | Enlace del mensajero. Solo viene en un cobro al entregar (ver §2.2). | ### Total según el método de pago (`CUSTOMER_PAYS`) Con `feeMode` `CUSTOMER_PAYS`, el total que paga el cliente depende del método que elige el pagador. - Al crear el cobro, `amount` usa la tarifa general. - Cuando el pagador elige el método, `amount` pasa a la tarifa de ese método. - `baseAmount` no cambia. Tú recibes siempre `baseAmount`. - Con `MERCHANT_PAYS`, `amount` es igual a `baseAmount` y no cambia. La respuesta de crear y `GET /api/v1/collect/:id` traen dos campos: | Campo | Significado | |-------|-------------| | `pricingByMethod` | Una fila por método ofrecido: `methodKey`, `feeAmount`, `taxAmount` y `totalAmount`. Es `null` cuando `amountIsFinal` es `true`. Si el campo no viene en la respuesta, no se pudo calcular en ese momento: consulta de nuevo con `GET /api/v1/collect/:id`. | | `amountIsFinal` | `true` cuando `amount` ya no puede cambiar: con `MERCHANT_PAYS`, en un cobro al entregar, o cuando el cobro ya no está pendiente (pagado, vencido o cancelado). Mientras el cobro está pendiente con `CUSTOMER_PAYS`, es `false` aunque el pagador ya haya elegido un método, porque puede cambiar de método. | Ejemplo con `CUSTOMER_PAYS` y `baseAmount` 5.000 (valores ilustrativos: la tarifa de cada método depende del plan del comercio): ```json { "amount": 5100, "baseAmount": 5000, "feeAmount": 100, "feeMode": "CUSTOMER_PAYS", "amountIsFinal": false, "pricingByMethod": [ { "methodKey": "breb", "feeAmount": 525, "taxAmount": 0, "totalAmount": 5525 }, { "methodKey": "nequi", "feeAmount": 600, "taxAmount": 0, "totalAmount": 5600 } ] } ``` Si el pagador elige `breb`, `amount` pasa a 5.525 y `feeAmount` pasa a 525. `methodKey` es la llave del método en el checkout. La lista sale del ruteo de pagos de tu comercio: trae los métodos que el checkout ofrece en ese cobro, y cambia si cambia el ruteo. `breb` y `nequi` son solo ejemplos. Otros valores posibles son `iion_app` (pago con la app iion pay) y `kushki_pse` (PSE). No asumas una lista fija: lee la que trae cada respuesta. El total final que pagó el cliente llega en el webhook `payment.completed`, en `amount`, `baseAmount` y `feeAmount`. Si una tarifa cambia entre crear y pagar, usa el valor del webhook. Un cupón aplicado en el checkout puede bajar `amount`. El total final siempre llega en el webhook `payment.completed`. ### Precio en USD, pago en pesos En lugar de `amount`, envía `priceCurrency: "USD"` y `priceAmount` (> 0, máximo 2 decimales). Nunca envíes `amount` junto con el par. ```json { "reference": "ORDER-12346", "priceCurrency": "USD", "priceAmount": 5, "customerName": "Juan Pérez", "customerEmail": "juan@example.com" } ``` - `currency` debe ser `COP` o no venir. `expirationMinutes` admite máximo 1440 (24 h). - La API convierte a COP con la TRM spot al crear el cobro y redondea al peso entero hacia arriba. La tasa queda congelada. - `amount` y `currency` de la respuesta son los COP que se cobran. Ejemplo: 5 USD con TRM 3171,7515 → 5 × 3171,7515 = 15858,7575, que se redondea hacia arriba a `amount` 15859 COP (`currency` "COP"). Quién asume la comisión lo indica `feeMode` (ver «Modelo de monto»). Si la asume el comercio, `amount` = `baseAmount` (15859) y `feeAmount` se descuenta de lo que recibe; si la paga el pagador, `amount` = `baseAmount` + `feeAmount`. El porcentaje de la comisión lo define el plan o el contrato del comercio. `feeMode` en el cobro puede pedir el modo, salvo que el contrato del comercio lo fije. - La respuesta incluye `price`: `{ "amount": 5, "currency": "USD", "fxRate": 3171.7515, "fxRateKind": "trm", "fxRateAt": "2026-10-15T14:00:00.000Z" }`. Es `null` sin precio en USD. - El checkout muestra el precio en grande (por ejemplo «5 USD») y debajo «Pagas en pesos $ 15.859 COP». Ese total en pesos es el `amount` del cobro: con la comisión asumida por el comercio es igual a `baseAmount`, y con la comisión a cargo del pagador incluye la comisión. - Los webhooks solo traen los COP. Para conciliar en USD, guarda `price` o consulta `GET /api/v1/collect/:id`. - Errores 400: `USD_PRICE_WITH_AMOUNT`, `USD_PRICE_INCOMPLETE`, `USD_PRICE_CURRENCY_INVALID`, `USD_PRICE_CURRENCY_NOT_COP`, `USD_PRICE_EXPIRATION_TOO_LONG`. Error 503 `RATE_UNAVAILABLE`: sin tasa vigente; reintenta o usa `amount` en COP. Error 403 `FEATURE_DISABLED`: función no habilitada. ## 2. Redirigir al pagador Redirige a `data.collectUrl`. Ahí tu cliente elige método y paga. No implementas la UI de pago. ### 2.1 Cobro directo por API (sin checkout) Tu sistema muestra el link, la llave o el QR de pago en su propia pantalla. Mismas credenciales y misma orden. Guía completa: https://pay.iionpay.com/docs/direct-api 1. `GET https://api.prod.iionpay.com/api/v1/collect/:id/methods` → cada método trae `requiredFields` (con `options` en los selects). Los datos que diste al crear la orden (`customerName`, `customerEmail`, `customerDocType`, `customerDocNumber`) no se vuelven a pedir. 2. `POST https://api.prod.iionpay.com/api/v1/collect/:id/pay` con `{ "method": "pse", "fields": { ... }, "returnUrl": "https://..." }`. `fields` lleva los `requiredFields` con la misma `key`. 3. Muestra según `flow`: `redirect` (PSE, Bancolombia) → redirige a `paymentUrl`; `push` (Nequi) → aviso para aprobar en su app; `qr` (Bre-B con `fields.brebMode: "qr"`) → muestra `qrImage` en un ``, o dibuja `keyValue` con tu librería de QR; `key` (Bre-B sin `brebMode`) → muestra la llave. QR y llave vencen en 10 minutos (`expiresAt`). - Con `flow` `qr`, la respuesta trae también `qrImage`: un PNG de 400 px en data URI (`"qrImage": "data:image/png;base64,iVBORw0KG..."`). `keyValue` es la fuente de verdad. `qrImage` es una ayuda generada desde `keyValue`. - Los clientes de correo bloquean las imágenes `data:`. Para correo o WhatsApp, envía `collectUrl` (el checkout hospedado), no el QR. 4. Si falta un dato del pagador, `/pay` responde 400 `PAYER_DATA_REQUIRED` con `error.missingFields` (por ejemplo `["bank"]` en PSE, o `["docNumber"]`). No se crea ningún cargo: pide esos campos y vuelve a llamar `/pay`. - En Bre-B, `fullName` es obligatorio. Si no lo envías (en `fields.fullName` o en `customerName` al crear el cobro), `/pay` responde 400 `PAYER_DATA_REQUIRED` con `missingFields: ["fullName"]` y no crea el cargo. 5. El pago se confirma solo por el webhook firmado. Si repites `/pay` con el mismo método antes de `expiresAt`, la API devuelve el mismo cargo (mismo `transactionId`). Con otro método, o después de `expiresAt`, se crea un cargo nuevo. No la llames en bucle. ### 2.2 Cobrar al entregar (Bre-B) Cobra cada pedido en la entrega con un QR o una llave Bre-B por el total del cobro. Guía completa: https://pay.iionpay.com/docs/cobrar-al-entregar También se conoce como cobro contraentrega. No es lo mismo que el pago en custodia (`escrow`), que retiene el dinero hasta que el comercio y el comprador confirman la entrega. En el panel, la custodia es la casilla «Pago en custodia». Desde el panel, sin integrar la API: 1. Entra a «Crear cobro». 2. Enciende el interruptor «Cobrar al entregar (QR Bre-B)». 3. Escribe el «Nombre del cliente». Es obligatorio. Al entregar, el mensajero ve solo las iniciales. 4. Escribe el precio. El panel muestra el total que paga el cliente antes de crear el cobro. 5. Pulsa «Crear cobro». 6. En la tarjeta «Cobrar en la entrega», copia o comparte el enlace con el mensajero. El mensajero también puede escanear el código de la tarjeta para abrir el enlace en su celular. Si el interruptor no aparece, la función no está disponible para tu cuenta por ahora. Por API, el flujo es: 1. Crea el cobro con `POST https://api.prod.iionpay.com/api/v1/collect` y `deliveryMode: true`. Guarda el `id` y el `deliveryUrl`. 2. Entrega el `deliveryUrl` (`https://pay.iionpay.com/c/:id/entrega`) al mensajero. 3. El mensajero muestra al cliente un QR Bre-B o una llave Bre-B por el total del cobro. 4. El cliente paga desde su app bancaria. 5. Confirma con el webhook `payment.completed`. Reglas: - Solo admite Bre-B y solo COP. Bre-B pide un mínimo de 5.000 COP. - `customerName` es obligatorio. - La orden vive 10080 minutos (7 días) si no envías `expirationMinutes`. - No se combina con custodia (`escrow`). - Cada solicitud de pago (QR o llave) vive 10 minutos. - Hay una sola solicitud a la vez. Si el mensajero pide el otro modo con la solicitud vigente, la API responde 409 `CHARGE_STILL_ACTIVE` con `activeMode` y `expiresAt`. - Si el cliente rechaza el pago, la orden vuelve a `PENDING` y se puede reintentar. Crear: ```bash curl -X POST https://api.prod.iionpay.com/api/v1/collect \ -H "X-Api-Key: $IION_API_KEY" \ -H "X-Api-Secret: $IION_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "amount": 5000, "currency": "COP", "reference": "PEDIDO-1042", "customerName": "Ana Pérez", "deliveryMode": true, "feeMode": "CUSTOMER_PAYS" }' ``` La respuesta `201` trae `deliveryUrl` y el desglose del precio. Los números del ejemplo son ilustrativos: la comisión depende del plan del comercio. ```json { "success": true, "data": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "reference": "PEDIDO-1042", "amount": 5525, "baseAmount": 5000, "feeAmount": 525, "netAmount": 5000, "feeMode": "CUSTOMER_PAYS", "currency": "COP", "status": "PENDING", "collectUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479", "deliveryUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479/entrega", "expiresAt": "2026-11-11T15:00:00.000Z" } } ``` El `amount` de la respuesta es el total que paga el cliente y no cambia al pagar. #### Cuánto paga el cliente El `amount` que envías es el monto base: el valor del pedido. El total que paga el cliente puede ser mayor, porque incluye la comisión de iion pay cuando la paga el cliente. Los números de esta sección son un ejemplo: la comisión depende del plan del comercio. `feeMode` define quién asume la comisión de este cobro (campo opcional; sin valor se usa el modo por defecto del comercio, y un contrato de tarifa con modo propio manda sobre el campo): | `feeMode` | El cliente paga | El comercio recibe | |-----------|-----------------|--------------------| | `CUSTOMER_PAYS` | `baseAmount` + `feeAmount` | `baseAmount` | | `MERCHANT_PAYS` | `baseAmount` | `baseAmount` − `feeAmount` | Ejemplo con `CUSTOMER_PAYS`: un cobro de `amount` 5.000 queda con comisión de 525 y total de 5.525. El cliente paga 5.525 y el comercio recibe 5.000. Campos que muestran el precio (en la respuesta de crear y en `GET /api/v1/collect/:id`): | Campo | Significado | |-------|-------------| | `amount` | Total que paga el cliente. | | `baseAmount` | Monto base: el valor del pedido. | | `feeAmount` | Comisión de iion pay. | | `netAmount` | Lo que recibe el comercio por el cobro. | | `feeMode` | Quién paga la comisión en este cobro. | - iion pay fija el total al crear el cobro. El total no cambia cuando el cliente paga. - El QR y la llave Bre-B cobran ese mismo total. - Si cambia la tarifa del comercio, el cambio aplica solo a los cobros nuevos. Los cobros ya creados conservan su total. - La vista del mensajero (`deliveryUrl`) muestra ese mismo total. - La API pública con `X-Api-Key` no tiene un endpoint de cotización. Para conocer el total, crea el cobro y lee `amount`. El panel de iion pay muestra la cotización antes de crear, con el mismo total que fija la creación. Consultar: `GET /api/v1/collect/:id` incluye `deliveryMode` (boolean) y `deliveryUrl` (string, o `null` si el cobro no es de entrega). ```bash curl https://api.prod.iionpay.com/api/v1/collect/f47ac10b-58cc-4372-a567-0e02b2c3d479 \ -H "X-Api-Key: $IION_API_KEY" -H "X-Api-Secret: $IION_API_SECRET" ``` Errores al crear: | HTTP | Código | Causa | |------|--------|-------| | 400 | `INVALID_COMBINATION` | `deliveryMode` junto con custodia (`escrow`). | | 400 | `COLLECT_AMOUNT_BELOW_MINIMUM` | El monto está bajo el mínimo de un cobro. | | 400 | `METHOD_NOT_AVAILABLE` | Bre-B no está disponible para este cobro. También responde así un monto bajo el mínimo de Bre-B. | | 400 | `CURRENCY_NOT_SUPPORTED` | La moneda no es COP. El cobro de entrega solo acepta COP. | | 400 | `PAYER_DATA_REQUIRED` | Falta `customerName`. La respuesta trae `missingFields`. | | 403 | `FEATURE_DISABLED` | La función no está disponible por ahora. | Errores al iniciar el pago: 400 `METHOD_NOT_ALLOWED` (un cobro de entrega solo acepta Bre-B), 409 `CHARGE_STILL_ACTIVE` y 403 `FEATURE_DISABLED`. Si la función se apaga, tampoco se crean QR ni llaves nuevos para los cobros de entrega que ya existen. Un QR o una llave vigente se puede pagar hasta que vence. #### Lote `POST https://api.prod.iionpay.com/api/v1/collect/batch` con `{ "orders": [ ... ] }`. Admite hasta 500 órdenes y procesa 5 a la vez. Cada fila tiene la forma de `POST /api/v1/collect`. `reference` es obligatoria en cada fila. La respuesta es HTTP 200. ```bash curl -X POST https://api.prod.iionpay.com/api/v1/collect/batch \ -H "X-Api-Key: $IION_API_KEY" -H "X-Api-Secret: $IION_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "orders": [ { "reference": "PEDIDO-1042", "amount": 5000, "currency": "COP", "customerName": "Ana Pérez", "deliveryMode": true }, { "reference": "PEDIDO-1043", "amount": 3000, "currency": "COP", "customerName": "Luis Gómez", "deliveryMode": true } ] }' ``` ```json { "success": true, "data": { "total": 2, "created": 1, "duplicates": 0, "failed": 1, "results": [ { "index": 0, "reference": "PEDIDO-1042", "ok": true, "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "amount": 5525, "baseAmount": 5000, "currency": "COP", "checkoutUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479", "deliveryUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479/entrega" }, { "index": 1, "reference": "PEDIDO-1043", "ok": false, "error": { "code": "AMOUNT_BELOW_MIN", "message": "El monto mínimo de un cobro es $5.000 COP" } } ] }, "error": null } ``` En cada fila `ok: true`, `baseAmount` es el monto base de la orden guardada y `amount` es el total que paga el cliente. Con `CUSTOMER_PAYS`, la base 5.000 queda con un total de 5.525 (valores ilustrativos). `baseAmount` es `null` si la orden no tiene monto base. Si una `reference` ya existe en una orden viva o pagada de tu comercio, la fila devuelve esa orden con `duplicate: true` y no crea otra. Reenviar el mismo lote no duplica cobros. Si esa orden es de otro modo (normal o contraentrega), la fila falla con `REFERENCE_ALREADY_EXISTS`. Una fila mal formada (un tipo incorrecto o un campo obligatorio ausente) rechaza el lote completo con HTTP 400. La API no crea ninguna fila. Cada fila `ok: true` trae `amount` (el total que paga el cliente en esa orden; en el ejemplo, base 5.000 y total 5.525, valores ilustrativos) y `currency` de la orden guardada, los mismos que devuelve `GET /api/v1/collect/:id`. En un duplicado son los de la orden existente, no los de la fila enviada. | Alcance | Código | Causa | |---------|--------|-------| | Lote | `BATCH_TOO_LARGE` | HTTP 400. Más de 500 filas. No se crea ninguna. | | Fila | `REFERENCE_REQUIRED` | La fila no trae `reference`. | | Fila | `DUPLICATE_IN_BATCH` | La `reference` ya aparece antes en el lote. | | Fila | `AMOUNT_BELOW_MIN` | Monto bajo el mínimo de un cobro. En un cobro individual, el mismo caso responde `COLLECT_AMOUNT_BELOW_MINIMUM`. | | Fila | `REFERENCE_LOCKED` | Otra llamada crea esa `reference`, o el candado no está disponible. Reintenta la fila. | | Fila | `REFERENCE_ALREADY_EXISTS` | La `reference` ya existe en una orden viva o pagada de otro modo (normal o contraentrega). Usa otra `reference`. | #### Webhooks del cobro al entregar - `payment.completed`: el cliente pagó. - `payment.attempt_failed`: el banco rechazó un intento. La orden sigue en `PENDING`. Trae `failureCode` (código del proveedor), `failureReason` (motivo en español), `attempt` (número del intento) y `status` `"PENDING"`. El vencimiento de la solicitud de 10 minutos no genera este evento. - `payment.failed`: la orden pasa a `FAILED`. Ahora trae `failureCode` y `failureReason` en todos los cobros. Si validas el cuerpo de forma estricta, acepta campos adicionales. ```json { "event": "payment.attempt_failed", "data": { "id": "4e7c2a91-...", "reference": "PEDIDO-1042", "amount": 45000, "currency": "COP", "status": "PENDING", "paidAt": null, "metadata": {}, "failureCode": "R000", "failureReason": "El banco del pagador rechazó el pago sin indicar el motivo.", "attempt": 1 }, "timestamp": "2026-11-04T12:15:01.000Z" } ``` Buenas prácticas: - Escucha el webhook firmado. Verifica la firma antes de actuar. - No marques el pedido como entregado sin `payment.completed`. - Un intento fallido no cierra el pedido: decide en tu sistema si avisas al cliente o al mensajero. - Usa una `reference` estable por pedido para que el reintento de un lote no duplique cobros. - Trata el `deliveryUrl` como un enlace de cobro y compártelo solo con el mensajero del pedido. ### 2.3 Embudo de venta del link de producto (`/s/`) Vende más de una vez a cada comprador desde el link de producto. Cada pieza tiene su interruptor por producto. Guía completa: https://pay.iionpay.com/docs/embudo-de-venta El embudo se activa por comercio. Si el comercio no lo tiene, el link funciona igual que antes. Las cuatro piezas: - **Order bump:** casilla sin marcar en el producto principal que suma un segundo producto al mismo cobro. El producto del bump es del mismo comercio, está visible, tiene la misma moneda y no es el principal. El producto principal y el del bump deben tener tipo (físico o digital). El cupón descuenta solo el producto principal. - **Upsell y downsell:** ofertas después del pago aprobado. Si el comprador acepta, se crea una orden nueva con sus datos llenos y paga otra vez (elige el medio). El downsell es una segunda oferta más económica: solo aparece si el comprador rechaza el upsell, y requiere el upsell activo. Cada orden nueva cobra su propia comisión. - **Urgencia y prueba social:** oferta con contador hasta una fecha real (al vencer, el precio vuelve al normal y el contador desaparece), «Quedan N» solo con stock definido, ventas (órdenes completadas) y reseñas de compradores con orden completada. El servidor calcula todo y nada se reinicia por visitante. - **Recuperación por correo:** recordatorio solo a compradores que dieron consentimiento. Aún no está disponible. Configuración en el panel: Productos → el producto → «Embudo de venta». Cada pieza tiene su interruptor. API del comercio (requiere la sesión del comercio con permiso `collect:read` para leer o `collect:create` para guardar; no se llama con `X-Api-Key` / `X-Api-Secret` del API de cobros): - `GET /api/v1/business/collect/products/:id/funnel`: devuelve `{ productId, available, config, commissions }`. Sin embudo guardado, todo viene apagado. `available: false` si el embudo no está activado para el comercio. `commissions` trae la comisión estimada de `bump`, `upsell`, `downsell` y `offer`. - `PUT /api/v1/business/collect/products/:id/funnel`: guarda y mezcla con lo existente (campo ausente = sin cambio, `null` = borrar). Responde igual que el `GET`. Campos de `config`: `bumpEnabled`, `bumpProductId` (uuid), `bumpAmount` (`null` = precio del producto ofrecido), `bumpHeadline` (máx. 80), `bumpText` (máx. 300), `upsellEnabled`, `upsellProductId`, `upsellAmount`, `upsellHeadline` (máx. 80), `downsellEnabled`, `downsellProductId`, `downsellAmount`, `downsellHeadline` (máx. 80), `offerEnabled`, `offerAmount` (menor que el precio del producto), `offerEndsAt` (ISO 8601, futura), `showStock`, `testimonialsEnabled`, `recoveryEnabled`. Los montos son >= 1 con máximo 2 decimales. | HTTP | Código | Causa | |------|--------|-------| | 403 | `FUNNEL_NOT_ENABLED` | El embudo no está activado para el comercio (solo `PUT`). | | 403 | `FEATURE_DISABLED` | Los productos no están disponibles. | | 404 | `PRODUCT_NOT_FOUND` | El producto no existe o no es del comercio. | | 422 | `FUNNEL_PRODUCT_NOT_OWNED` | El producto ofrecido no es del comercio. | | 422 | `FUNNEL_CURRENCY_MISMATCH` | El producto ofrecido tiene otra moneda. | | 422 | `FUNNEL_PRODUCT_IS_MAIN` | El producto ofrecido es el principal. | | 422 | `FUNNEL_PRODUCT_NOT_AVAILABLE` | El producto ofrecido no está visible. | | 422 | `FUNNEL_OFFER_INVALID` | La oferta necesita un precio menor al del producto y una fecha futura. | | 422 | `FUNNEL_PIECE_INCOMPLETE` | Una pieza está activa y no tiene producto. | | 422 | `FUNNEL_AMOUNT_INVALID` | Un monto es menor que 1 o tiene más de 2 decimales. | | 422 | `FUNNEL_TEXT_TOO_LONG` | Un título o texto supera el máximo. | | 422 | `FUNNEL_PRODUCT_KIND_REQUIRED` | El producto principal o el del bump no tiene tipo (físico o digital). | | 422 | `FUNNEL_DOWNSELL_REQUIRES_UPSELL` | El downsell está activo y el upsell no. El downsell solo se ofrece después de un upsell rechazado. | Los agentes conectados al MCP usan `product_funnel_get` y `product_funnel_set` con los mismos campos y errores. ## 3. Recibir el webhook (fuente de verdad) Cuando la orden se paga o falla, iion pay hace `POST` a la URL de tu webhook: la de la API key que creó el cobro (campo `url` de `PUT /api/v1/collect/webhook`) o, si la llave no tiene, la del webhook general del panel (ver «Webhook general vs. webhook por API key»). **Eventos:** `payment.completed`, `payment.failed` (trae `failureCode` y `failureReason`), `payment.attempt_failed` (solo cobro al entregar; ver §2.2). **Body:** ```json { "event": "payment.completed", "data": { "id": "f47ac10b-...", "reference": "wc-order-1042", "amount": 151235, "baseAmount": 150000, "feeAmount": 1235, "currency": "COP", "status": "COMPLETED", "paidAt": "2026-06-25T14:45:00.000Z", "metadata": { "wooOrderId": 1042 } }, "timestamp": "2026-06-25T14:45:00.123Z" } ``` **Headers:** ``` X-IION-Signature: sha256= X-IION-Timestamp: 1719330300000 Content-Type: application/json User-Agent: iion-pay-Webhook/1.0 ``` También llegan como `X-NIIO-*` con el mismo valor, por compatibilidad. **Reintentos:** hasta 5 intentos con backoff (inmediato, 5min, 30min, 2h, 24h). Responde `2xx` rápido para detenerlos. Tu handler **debe ser idempotente** (el mismo evento puede llegar más de una vez). ### Verificar la firma (OBLIGATORIO) La firma es `HMAC-SHA256` sobre `"{X-IION-Timestamp}.{RAW_BODY}"`, con tu `webhookSecret`. **Usa el cuerpo CRUDO de la petición tal cual llegó.** No re-serialices el JSON: el orden de claves y el escaping deben ser idénticos a los que iion pay firmó. ```php 5 * 60 * 1000) { http_response_code(401); exit('stale'); } $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret); if (!hash_equals($expected, $header)) { // comparación constant-time http_response_code(401); exit('invalid signature'); } $event = json_decode($rawBody, true); // recién AHORA parseas // ... procesa $event['event'] / $event['data'] de forma idempotente ... http_response_code(200); ``` Equivalente en Node.js: ```js const crypto = require('crypto'); function verify(rawBody, timestamp, signature, secret) { if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) return false; // anti-replay const expected = 'sha256=' + crypto.createHmac('sha256', secret) .update(`${timestamp}.${rawBody}`).digest('hex'); const a = Buffer.from(expected); const b = Buffer.from(String(signature)); if (a.length !== b.length) return false; // timingSafeEqual lanza error si difieren return crypto.timingSafeEqual(a, b); } ``` ### Webhook general vs. webhook por API key Tu comercio tiene un **Webhook general** (URL, eventos y secreto de firma). Además, cada API key puede tener su propio webhook: URL `https://` pública, lista de eventos (vacía = todos) y secreto de firma propio con formato `whsec_…`, distinto del general. > Disponible de forma gradual. La función se activa por negocio. Si en la página de tu llave ves el aviso «Los avisos de esta llave van al Webhook general.», tus avisos van al Webhook general. Cada aviso llega a un solo destino, nunca a los dos: | Caso | URL de destino | Secreto de firma | |---|---|---| | Cobro creado por la API con una llave que tiene webhook propio | URL de esa llave | Secreto de esa llave | | Cobro creado por la API con una llave sin webhook propio | URL del webhook general | Secreto del webhook general | | Cobro sin llave (link, tienda, botón o panel) | URL del webhook general | Secreto del webhook general | | Cobro anterior a esta función | URL del webhook general | Secreto del webhook general | | Cobro de una llave revocada que tenía webhook propio | URL de esa llave | Secreto de esa llave | | Evento sin cobro (por ejemplo `settlement.closed`) | URL del webhook general | Secreto del webhook general | iion pay decide el destino en cada evento. Usa la configuración actual de la llave que creó el cobro, no la del momento de crear el cobro. Si agregas una URL a la llave, los eventos siguientes de sus cobros van a esa URL. Los reintentos de un aviso ya enviado van a la misma URL de ese aviso. La firma no cambia de formato: `HMAC-SHA256` de `${timestamp}.${body}` con las mismas cabeceras de siempre. Solo cambia el secreto. **Valida cada aviso con el secreto del destino que configuraste**: el de la llave si llegó a la URL de la llave, el general si llegó a la URL general. **Dónde se configura:** panel, «API keys», abre la llave, sección Webhook (URL, eventos, probar, ver o regenerar el secreto, quitar). Al quitar el webhook propio, la llave vuelve a usar el webhook general. La pantalla del webhook del comercio se llama ahora «Webhook general». **Aviso al regenerar el secreto de una llave:** los reintentos pendientes salen firmados con el secreto nuevo. Copia el secreto nuevo en tu servidor apenas lo regeneres: hasta que lo hagas, esos avisos no pasarán tu validación de firma. Hazlo en un momento de poco tráfico. ## Registrar tu webhook por API El webhook por API key es el webhook de la llave que hace la llamada. Se distingue del webhook general del comercio, que se configura en el panel. Cada llave registra el suyo. Este registro exige el permiso `collect:webhook`. El permiso se otorga al crear la llave desde la tarjeta «Deja que tu agente integre iion pay» de Integraciones en el panel, o en los permisos de la llave. ``` PUT https://api.prod.iionpay.com/api/v1/collect/webhook X-Api-Key: niio_live_... X-Api-Secret: niio_secret_... Content-Type: application/json { "url": "https://tu-dominio.com/webhooks/iionpay", "events": ["payment.completed", "payment.failed"] } ``` - `url` es obligatoria. Debe ser `https` y pública. - `events` es opcional. Una lista vacía `[]` = todos los eventos. Si lo omites, los eventos guardados no cambian (en el primer registro: todos). Respuesta: ```json { "success": true, "data": { "url": "https://tu-dominio.com/webhooks/iionpay", "events": ["payment.completed", "payment.failed"], "secret": "whsec_..." } } ``` El `secret` llega solo en la respuesta que lo crea (el primer `PUT` de la llave). Guárdalo en ese momento como `IIONPAY_WEBHOOK_SECRET`. Un `PUT` posterior devuelve `"secret": null` y conserva el mismo secreto. Si lo perdiste, regenéralo en el panel (API keys, la llave, Webhook). **Valida la firma de cada webhook con ese `whsec_`** (ver «Verificar la firma»). Otros endpoints (mismos headers): - `GET /api/v1/collect/webhook`: devuelve `url` y `events`, sin el secreto. - `PUT /api/v1/collect/webhook` responde `200` con el cuerpo de arriba. - `POST /api/v1/collect/webhook/test`: envía un aviso de prueba firmado (evento `test.ping`) a la URL de la llave. Responde `201` con `{ logId, url, delivered, responseStatus, responseBody, attempts }`. `delivered: true` = tu servidor respondió 2xx. Responde `400` si la llave no tiene URL y `429 WEBHOOK_TEST_RATE_LIMITED` con más de 5 pruebas por minuto por comercio. El aviso `test.ping`: - Llega aunque `events` de la llave no lo incluya. - Se envía una sola vez. No tiene reintentos. - Lleva la misma firma que un aviso real. - Su cuerpo trae `data.test: true`, `data.status: "TEST"`, `data.amount: 0`, `data.baseAmount: 0`, `data.feeAmount: 0` y `data.reference` con el prefijo `TEST-`. - Ningún pago ocurrió. Tu handler debe verificar la firma y responder `2xx`. No lo proceses como pago ni actualices pedidos con él. ```json { "event": "test.ping", "data": { "test": true, "id": "", "reference": "TEST-1a2b3c4d", "amount": 0, "baseAmount": 0, "feeAmount": 0, "currency": "COP", "status": "TEST", "paidAt": null, "metadata": { "message": "..." } }, "timestamp": "2026-11-12T14:00:00.000Z" } ``` Errores: - `403 API_KEY_PERMISSION_DENIED` sin el permiso `collect:webhook`: crea la llave desde la tarjeta «Deja que tu agente integre iion pay». - `400` si la URL no es `https` o no es pública: usa una URL `https` pública. - `403 FEATURE_DISABLED` si el webhook por llave no está habilitado para el comercio: pídele al usuario que configure el webhook general del comercio en el panel, en Integraciones → Webhooks («Webhook general»), y que copie ahí la «Clave del webhook» como `IIONPAY_WEBHOOK_SECRET`. ## 4. callbackUrl vs webhook - **`callbackUrl`** es solo la URL de retorno visual tras pagar. **No está firmada** y el pagador puede no completar el regreso. **No marques el pedido como pagado solo por el callback.** - **El webhook** (§3) es la confirmación fiable. Si necesitas confirmar en el callback (UX), **reconsulta** el estado con `GET /api/v1/collect/:id` antes de actuar. ## 5. Consultar el estado de una orden ``` GET https://api.prod.iionpay.com/api/v1/collect/{orderId} X-Api-Key: niio_live_... X-Api-Secret: niio_secret_... ``` Devuelve la orden con su `status` actual y el desglose (`amount`/`baseAmount`/`feeAmount`, `taxAmount`, `netAmount` y `feeMode`). **Estados:** `PENDING`, `WAITING_TRANSFER`, `PROCESSING`, `CREDITING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED`. `TEST` no es un estado de una orden: solo aparece en el aviso de prueba `test.ping` (ver «Registrar tu webhook por API»). El `GET` trae también estos campos: | Campo | Significado | |-------|-------------| | `allowedMethods` | Métodos que admite el cobro. | | `selectedMethod` | Método que eligió el pagador. `null` si aún no eligió. | | `confirmationState` | Finalidad del pago, aparte de `status`: `AUTHORIZED`, luego `CONFIRMED`, luego `SETTLED`. `null` si el cobro no pasó por esa política. | | `resolutionStatus` | Lo que pasó después del pago, aparte de `status`: `NONE`, `DISPUTED`, `PARTIALLY_REFUNDED`, `REFUNDED` o `CHARGEBACK`. | | `deliveryMode` | `true` en un cobro al entregar (§2.2). | | `deliveryUrl` | Enlace del mensajero. `null` si el cobro no es de entrega. | ## 6. Reembolsos La API de collect **no expone reembolsos**. Gestiónalos desde el panel de iion pay o con soporte (`soporte@iionpay.com`). ## 7. Pruebas No hay sandbox ni llaves de prueba. Prueba contra producción con tus API keys y montos pequeños, desde el monto mínimo (ver «Monto mínimo» en §1). Las API keys se crean en el panel de negocios, en Integraciones → API keys. Para recibir webhooks en local, expón tu servidor con ngrok/localtunnel y registra la URL pública como webhook general en el panel, o regístrala por API con `PUT /api/v1/collect/webhook` (campo `url`) y usa `POST /api/v1/collect/webhook/test` para enviar un aviso de prueba firmado. **Checklist pre-producción:** creas órdenes OK · el `collectUrl` carga · recibes el webhook · tu handler es idempotente · verificas `X-IION-Signature` · manejas errores de la API · el `callbackUrl` redirige bien. ## Errores Formato estándar: ```json { "success": false, "data": null, "error": { "code": "...", "message": "..." } } ``` | HTTP | Causa | |------|-------| | 400 | Body inválido (revisa campos requeridos). | | 400 `PAYER_DATA_REQUIRED` | Cobro directo (`/pay`): faltan datos del pagador. `error.missingFields` lista cuáles (`bank` en PSE). No se crea cargo: completa y reintenta. | | 401 | API key/secret inválidos o merchant no activo. | | 404 | Orden no encontrada (o no pertenece a tu merchant). | | 429 | Rate limit (si aplica). | Códigos `403` al crear un cobro: | Código | Causa | Qué hacer | |--------|-------|-----------| | `KYC_OR_KYB_REQUIRED` | El comercio no tiene KYB aprobado ni KYC aprobado del dueño. | Pide al usuario que verifique su negocio en el panel, sección Verificación. Reintenta cuando quede aprobada. | | `MERCHANT_SUSPENDED` | El comercio está suspendido. | No reintentes. Pide al usuario que contacte a soporte. | ## Agentes de IA: conectar por MCP Un agente de IA se conecta a iion pay con el protocolo MCP (Model Context Protocol). Un solo servidor sirve a todos los clientes. ### URL y autenticación - URL del servidor: `https://mcp.iionpay.com/api/v1/mcp` - Autenticación: OAuth 2.1 con registro dinámico de cliente y PKCE `S256`. - El comercio autoriza el acceso con su cuenta de iion pay. ### Permisos Cada permiso incluye los anteriores. - `read-only`: 22 herramientas, solo lectura. - `business-sales`: suma crear, consultar y cancelar cobros. Son 26 herramientas. - `business-store`: suma operar tienda y catálogo. Son 74 herramientas. El total de 74 supone que todas las banderas del servidor MCP están encendidas. ### Qué mueve dinero - Ninguna herramienta envía, retira ni transfiere dinero. `create_charge` y `membership_renewal_link` generan links que el cliente paga: el dinero entra al comercio solo cuando el cliente paga. - Ninguna herramienta envía ni retira fondos. - `business_payout` solo consulta el historial de retiros. ### Herramientas Cada fila indica el permiso mínimo de la herramienta, si lee o escribe y si mueve dinero. | Herramienta | Permiso mínimo | Lee o escribe | ¿Mueve dinero? | |---|---|---|---| | business_report | read-only | Lee | No | | business_operations | read-only | Lee | No | | business_payin | read-only | Lee | No | | business_profile | read-only | Lee | No | | business_balance | read-only | Lee | No | | business_payout | read-only | Lee | No | | business_webhooks | read-only | Lee | No | | business_settlements | read-only | Lee | No | | business_funds_summary | read-only | Lee | No | | business_kyb_status | read-only | Lee | No | | business_reconciliation | read-only | Lee | No | | business_summary | read-only | Lee | No | | business_daily_series | read-only | Lee | No | | business_fees_paid | read-only | Lee | No | | business_apps_metrics | read-only | Lee | No | | business_products | read-only | Lee | No | | get_integration_docs | read-only | Lee | No | | store_overview | read-only | Lee | No | | store_memberships | read-only | Lee | No | | store_bookings | read-only | Lee | No | | store_events | read-only | Lee | No | | store_vouchers | read-only | Lee | No | | create_charge | business-sales | Escribe | **Sí** | | get_charge | business-sales | Lee | No | | list_charges | business-sales | Lee | No | | cancel_charge | business-sales | Escribe | No | | booking_cancel | business-store | Escribe (destructiva) | No | | booking_mark_balance_paid | business-store | Escribe | No | | membership_cancel | business-store | Escribe (destructiva) | No | | membership_renewal_link | business-store | Escribe | **Sí** | | event_ticket_void | business-store | Escribe (destructiva) | No | | event_cancel | business-store | Escribe (destructiva) | No | | voucher_void | business-store | Escribe (destructiva) | No | | redemption_lookup | business-store | Lee | No | | redemption_consume | business-store | Escribe | No | | order_update_fulfillment | business-store | Escribe | No | | store_catalog | business-store | Lee | No | | app_install | business-store | Escribe | No | | app_uninstall | business-store | Escribe (destructiva) | No | | membership_plan_create | business-store | Escribe | No | | membership_plan_update | business-store | Escribe | No | | membership_plan_archive | business-store | Escribe (destructiva) | No | | voucher_product_create | business-store | Escribe | No | | voucher_product_update | business-store | Escribe | No | | voucher_product_archive | business-store | Escribe (destructiva) | No | | voucher_product_image_set | business-store | Escribe | No | | booking_service_create | business-store | Escribe | No | | booking_service_update | business-store | Escribe | No | | booking_service_archive | business-store | Escribe (destructiva) | No | | booking_service_schedules_set | business-store | Escribe (destructiva) | No | | event_create | business-store | Escribe | No | | event_update | business-store | Escribe | No | | event_archive | business-store | Escribe (destructiva) | No | | event_image_set | business-store | Escribe | No | | event_ticket_type_create | business-store | Escribe | No | | event_ticket_type_update | business-store | Escribe | No | | event_ticket_type_archive | business-store | Escribe (destructiva) | No | | product_create | business-store | Escribe | No | | product_update | business-store | Escribe | No | | product_archive | business-store | Escribe (destructiva) | No | | product_rotate_link | business-store | Escribe (destructiva) | No | | product_image_add | business-store | Escribe | No | | store_draft_list | business-store | Lee | No | | store_draft_create | business-store | Escribe | No | | store_draft_update | business-store | Escribe | No | | store_template_set | business-store | Escribe | No | | store_brand_set | business-store | Escribe | No | | store_publish | business-store | Escribe (destructiva) | No | | store_unpublish | business-store | Escribe (destructiva) | No | | store_credits_balance | business-store | Lee | No | | store_builder_run | business-store | Escribe (destructiva) | No (gasta créditos) | | store_builder_job_status | business-store | Lee | No | | image_upload_link_create | business-store | Escribe | No | | image_upload_status | business-store | Lee | No | ### Instalar Claude (web y escritorio): abre el directorio `https://claude.ai/directory/iion-pay` y añade el conector iion pay. Claude Code: ejecuta en la terminal: ```bash claude mcp add --transport http iion-pay https://mcp.iionpay.com/api/v1/mcp ``` Codex: ejecuta en la terminal: ```bash codex mcp add iion-pay --url https://mcp.iionpay.com/api/v1/mcp ``` Gemini CLI: ejecuta en la terminal: ```bash gemini mcp add --transport http iion-pay https://mcp.iionpay.com/api/v1/mcp ``` ### WhatsApp y Telegram Niia, el asistente de iion pay, atiende por WhatsApp y Telegram. Esos canales no usan MCP. El comercio los vincula con un código que genera en el panel de iion pay. La página no publica números de teléfono. ### Lectura de la documentación por agentes Un agente lee la documentación de iion pay de tres formas: - `https://pay.iionpay.com/llms.txt`: índice de la documentación. - `https://pay.iionpay.com/llms-full.txt`: toda la integración en un solo archivo. - Herramienta `get_integration_docs`: devuelve la documentación pública. Sin tema, devuelve el índice de secciones. Página completa: `https://pay.iionpay.com/docs/mcp`