Documentación para desarrolladores de Pharos
Usa este hub para integrar pagos de Pharos, lanzar el checkout hospedado y conectar tu backend con los flujos principales de la API.
Autenticación
Todos los endpoints `/api/v1` requieren tu API key de negocio en el header `x-api-key`.
- Crea y administra keys desde la configuración de desarrolladores en backoffice.
- Usa keys de solo lectura para flujos de consulta y permisos más amplios para flujos de escritura.
Primera request
Empieza con una request autenticada simple para validar tu key, el entorno y el manejo de respuestas.
- Lista productos o payment links antes de intentar operaciones de escritura.
- Trata todas las respuestas de la API como scoped al negocio autenticado por la key.
Products
Products y prices definen qué puede comprar un buyer a través de payment links y checkout hospedado.
- Usa los endpoints de Products para obtener el catálogo expuesto a tu integración.
- Mapea IDs de producto y precio antes de crear o actualizar payment links.
Payment Links
Los payment links son URLs reutilizables de checkout hospedado. Al iniciar el flujo interactivo se crea o reanuda una checkout session para ese link.
- Crea links para ofertas que quieras compartir desde tu sitio, flujos de CRM o campañas.
- Recupera y actualiza links vía API cuando necesites sincronizar estado o contenido.
Flujo de checkout hospedado
Pharos hospeda la experiencia de checkout. Tu integración decide cuándo enviar al buyer al checkout y cómo reconciliar el resultado.
- Usa Payment Links para ofertas reutilizables o Checkout Sessions para carritos controlados por tu backend.
- Maneja la finalización y el seguimiento en tus propios sistemas usando webhook events.
Webhooks
Usa entregas de webhooks para reaccionar desde tu backend a eventos de checkout, pagos y suscripciones.
- Valida `x-pharos-signature` con tu signing secret.
- Trata las entregas como at-least-once y haz tus handlers seguros frente a duplicados.
Manejo de errores
Diseña tu integración para manejar de forma explícita errores de validación, autorización y recursos inexistentes.
- Espera `401` cuando la API key falte, sea inválida o no tenga permisos.
- Espera `404` cuando el recurso scoped al negocio no exista.
Próximos pasos
Cuando el flujo principal funcione, avanza desde la primera request hacia una integración lista para producción.
- Conecta tu catálogo con products y prices.
- Publica payment links o lanza checkout hospedado desde tu sitio.
- Suscríbete a webhook events antes de salir a producción.