# NIIO Pay — Cobros (Payin) y Dispersiones (Payout)

> API de cobros (payin) y dispersiones (payout) para comercios en Colombia. Un
> comercio crea una orden de cobro vía REST, redirige a su cliente a un checkout
> hosted (`pay.niiopay.com/c/:id`) donde el cliente paga con PSE, Nequi, Daviplata,
> Bancolombia, Efecty, tarjeta o criptomonedas (BTC, ETH, USDT, USDC), y el
> comercio recibe un webhook firmado cuando el pago se completa o falla. También
> puede dispersar fondos de su saldo a cuentas bancarias (`BANK`) o llaves Bre-B
> (`BREB`) en Colombia, en COP.

## Cómo integrar (flujo mínimo)

1. `POST https://api.prod.niiopay.com/api/v1/collect` con `X-Api-Key` + `X-Api-Secret` → devuelve `collectUrl`.
2. Redirige al cliente a `collectUrl`. El checkout hosted maneja toda la UI de pago.
3. Recibe el webhook `POST` a tu `webhookUrl` (`payment.completed` / `payment.failed`; con eventos ampliados también `payment.expired|cancelled|confirmed|refunded|chargeback`, `refund.*` y `settlement.closed`, el cierre diario de liquidaciones). **Verifica la firma HMAC-SHA256** (`X-NIIO-Signature`). El webhook es la fuente de verdad.
4. (Opcional) Reconsulta con `GET https://api.prod.niiopay.com/api/v1/collect/:id`.
5. (Opcional) Lista tus transacciones con `GET /api/v1/collect` (filtros `status`, `limit`, `offset`) y concilia totales con `GET /api/v1/collect/stats`.

## Notas clave para agentes

- **Fee on-top 0.05%:** pides `amount` (lo que **recibes**, `baseAmount`); el pagador paga `amount + fee`. La respuesta trae `amount` (paga el pagador), `baseAmount` (recibes), `feeAmount`.
- **Idempotencia:** usa `reference` (tu ID único) al crear; tu handler de webhook debe ser idempotente (el mismo evento puede llegar más de una vez).
- **Un cobro completado puede revertirse:** un reembolso o contracargo llega como evento NUEVO. Si entregas mercancía, espera `payment.confirmed`, no solo `payment.completed`.
- **No confíes en el `callbackUrl`** (retorno visual, sin firma) para marcar como pagado. Usa el webhook o reconsulta el estado.
- **No hay sandbox separado:** las pruebas se hacen contra producción con credenciales de prueba y montos pequeños.
- Las credenciales (`niio_live_...` / `niio_secret_...`) se solicitan al contacto NIIO; aún no hay panel self-service.

## Documentación

- [Inicio](https://pay.niiopay.com/): qué es NIIO Pay, métodos disponibles, comisión y preguntas frecuentes. ([English](https://pay.niiopay.com/en))
- [Inicio Rápido](https://pay.niiopay.com/docs/quick-start): crea tu primer cobro en 5 minutos.
- [Autenticación](https://pay.niiopay.com/docs/authentication): headers `X-Api-Key` / `X-Api-Secret`.
- [Referencia de API](https://pay.niiopay.com/docs/api-reference): endpoints `POST /api/v1/collect` y `GET /api/v1/collect/:id`.
- [Dispersiones (Payout)](https://pay.niiopay.com/docs/payout): dispersar saldo a cuentas bancarias o llaves Bre-B en Colombia (`GET /payout/methods`, `POST /payout`).
- [Métodos de Pago](https://pay.niiopay.com/docs/payment-methods): PSE, Nequi, Daviplata, Bancolombia, Efecty, tarjetas, cripto.
- [Webhooks](https://pay.niiopay.com/docs/webhooks): eventos, firma HMAC-SHA256, reintentos.
- [Pagos de Agentes IA (x402)](https://pay.niiopay.com/docs/x402): protocolo x402, HTTP 402 + USDC en Polygon; el agente firma y NIIO liquida on-chain.
- [Manejo de Errores](https://pay.niiopay.com/docs/errors): formato de error y códigos HTTP.
- [Pruebas](https://pay.niiopay.com/docs/testing): probar contra producción, checklist pre-producción.
- [SDKs y Librerías](https://pay.niiopay.com/docs/sdks): ejemplos por lenguaje y plugin de WooCommerce.

## Optional

- [OpenAPI JSON](https://pay.niiopay.com/api/openapi.json): especificación cruda de la API.
- [Referencia interactiva](https://pay.niiopay.com/api/docs): Scalar — ejecuta cada endpoint en vivo con tus API keys.
- [Contenido completo para LLMs](https://pay.niiopay.com/llms-full.txt): toda la integración inlineada en un archivo.