# OrvenPay

> Pasarela de pagos en criptomonedas custodial con API REST (JSON, cabecera X-Api-Key en https://api.orvenpay.com/v1), página de pago alojada, webhooks firmados con HMAC-SHA256 (X-OrvenPay-Signature), saldos y retiros, y una API Gateway compatible con plugins (https://api.orvenpay.com/gateway, api_key + verify_hash).

Para integrar de extremo a extremo basta con leer la documentación completa: https://orvenpay.com/llms-full.txt. Importes siempre como strings decimales; crea las facturas sólo en el servidor; entrega el pedido sólo con el webhook invoice.completed verificado.

## Documentación

- [Documentación completa (Markdown, un archivo)](https://orvenpay.com/llms-full.txt): todo el contenido para agentes de IA: endpoints, parámetros, respuestas, webhooks, errores, monedas, comisiones y recetas.
- [Documentación en Markdown](https://orvenpay.com/docs.md): el mismo contenido (alias para personas).
- [OpenAPI 3.1](https://orvenpay.com/openapi.json): especificación de la API nativa, endpoints públicos, API Gateway y webhooks.
- [Documentación HTML](https://orvenpay.com/docs): versión web con buscador.

## Guías principales

- [Introducción y conceptos](https://orvenpay.com/docs#introduccion): Qué es OrvenPay, modelo custodial, dirección única por factura, saldos, comisión y fee de red.
- [Inicio rápido en 5 minutos](https://orvenpay.com/docs#inicio-rapido): Cuenta, tienda, API key, primera factura, redirección y webhook verificado.
- [Referencia rápida de endpoints](https://orvenpay.com/docs#referencia-rapida): Todos los endpoints públicos en una tabla: método, ruta, autenticación y propósito.
- [Autenticación y API keys](https://orvenpay.com/docs#autenticacion): X-Api-Key en la API nativa, api_key en la API Gateway, rotación y buenas prácticas.
- [Facturas](https://orvenpay.com/docs#facturas): Crear (fiat o cripto), parámetros, importes y redondeo, idempotencia por orderNumber, expiración, metadata, consulta, listado y cancelación.
- [Estados y ciclo de vida](https://orvenpay.com/docs#estados): Máquina de estados de la factura, eventos, tolerancia de pago insuficiente, sobrepagos, pagos tardíos y casos límite.
- [Webhooks](https://orvenpay.com/docs#webhooks): Eventos, payload, cabeceras, verificación HMAC-SHA256 (Node.js, Python, PHP, Go), cuerpo crudo, reintentos, orden, idempotencia y protección anti-replay.
- [Errores](https://orvenpay.com/docs#errores): Formato de error y catálogo completo de códigos de la API nativa y pública.

## Optional

- [Página de pago alojada](https://orvenpay.com/docs#checkout): Qué hace la página de pago alojada (invoiceUrl) y endpoints públicos del checkout (estado, elección de moneda, SSE).
- [White Label](https://orvenpay.com/docs#white-label): Plan por tienda: datos de pago completos por API (dirección, importe, QR), white_label en /shops y tu marca en el checkout; comisión 1 % por defecto.
- [API Gateway](https://orvenpay.com/docs#api-gateway): Capa compatible con plugins y SDK de pasarelas (api_key + verify_hash HMAC-SHA1): endpoints, parámetros, respuestas estándar/White Label, callbacks, verificación y códigos de error.
- [Saldos y retiros](https://orvenpay.com/docs#saldos-retiros): Saldos por moneda, maduración de créditos, libreta de direcciones con activación, mínimos, fees, revisión, límite diario, pausa e idempotencia de retiros.
- [Monedas y redes](https://orvenpay.com/docs#monedas): Monedas soportadas con red, contrato, confirmaciones, decimales, mínimos y fee de red; monedas fiat de precio.
- [Comisiones y mínimos](https://orvenpay.com/docs#comisiones): Comisión por plan (0,5 % estándar, 1 % White Label), quién paga comisión y fee de red, cómo se descuenta del crédito y ejemplos numéricos.
- [Límites y rate limits](https://orvenpay.com/docs#limites): Peticiones por minuto por API key e IP, cupo de facturas por cuenta, tamaños máximos y cabeceras de rate limit.
- [Seguridad](https://orvenpay.com/docs#seguridad): Buenas prácticas: secretos, verificación de webhooks, no confiar en el navegador, importes, idempotencia y respuesta ante incidentes.
- [Recetas de integración](https://orvenpay.com/docs#recetas): Código completo listo para copiar: bots de Telegram (python-telegram-bot, grammY), Next.js, Express, PHP/Laravel y plugins de e-commerce vía API Gateway.
- [Pruebas](https://orvenpay.com/docs#pruebas): Checklist antes de producción, webhooks en local con un túnel, firmar payloads de prueba y pago real de bajo importe.
- [Preguntas frecuentes](https://orvenpay.com/docs#faq): Respuestas cortas a las dudas más comunes de integración.
- [Changelog](https://orvenpay.com/docs#changelog): Cambios relevantes de la API y la documentación.