UNIPaaS/agent-skills

Unipaas

Fundamentos

Unipaas proporciona pagos embebidos de extremo a extremo para plataformas digitales y marketplaces (SaaS, economía gig, marketplaces B2B/B2C). Puedes incorporar vendedores (subcomerciantes), aceptar pagos, gestionar cuentas (saldos) y realizar pagos, mientras controlas los flujos de dinero y cumples con PSD2/PCI.

Obtén una clave de sandbox. Crea una cuenta de prueba gratuita en https://portal.unipaas.com/signup. La cuenta de prueba es ilimitada y siempre está disponible. Encuentra tu Clave Privada en el portal, en la sección de desarrollador/claves. Las credenciales de Sandbox y Producción son completamente independientes y no comparten datos.

URLs base.

• Sandbox: https://sandbox.unipaas.com/platform
• Producción (Live): https://api.unipaas.com/platform

Dos modos de autenticación (detalles en references/auth.md).

1. Servidor a servidor: envía tu Clave Privada como Authorization: Bearer {{PRIVATE_KEY}} directamente en las llamadas API (creación de checkout, pagos entrantes, cuentas, pagos, incorporación). La clave privada debe permanecer en el servidor.
2. Flujo de dos pasos /authorize (para embebidos de plataforma del lado del cliente): tu servidor hace POST de la clave privada a /authorize con scopes y (normalmente) un vendorId, y recibe un accessToken temporal. El cliente usa ese token de acceso — nunca la clave privada.

Idempotencia. Para evitar la ejecución duplicada en reintentos, agrega un encabezado requestId: <id> a las solicitudes POST. La misma requestId aplicada varias veces produce un único resultado. Los ID de solicitud son válidos durante 24 horas.

Mapa de decisión

Cuatro productos, tres niveles de integración. Elige el nivel que coincida con tu capacidad de desarrollo y tu postura PCI.

Producto	Sin código	Esfuerzo bajo	Esfuerzo medio
Incorporación	Enlace de incorporación alojado	UI embebida (unipaas.components)	API de incorporación
Aceptar pagos	Enlace de pago (portal)	Página de pago / SDK web	API de pago entrante (servidor a servidor)
Gestión de cuentas	Vista del portal	Componente de cuenta/saldo	API de cuentas
Pagar fondos	Pago manual/programado vía portal	Formulario de pago / Componente de cuenta	API de pagos

Orientación:

• ¿Quieres cero código? Usa Enlace de pago, enlace de incorporación alojado, pagos desde el portal.
• ¿Quieres tu propia UI con poco esfuerzo y PCI reducido? Usa la Página de pago (redirección), campos seguros del SDK web, o embebidos web del comprador; usa embebidos de plataforma para incorporación/saldo/portal.
• ¿Quieres control total / marca blanca / app nativa? Usa las API. La API de pago entrante (datos de tarjeta en bruto) requiere PCI SAQ D.

Nota: una transacción enviada sin un vendorId se registra contra la cuenta de la plataforma.

Rutas de pago del lado del cliente

Consulta references/web-sdk.md para los pasos completos. Dos rutas de pago del comprador, ambas autenticadas con el sessionToken devuelto por un POST /pay-ins/checkout del lado del servidor — no el token de acceso /authorize.

1. SDK de campos seguros — carga https://cdn.unipaas.com/unipaas.sdk.js (expone el global Unipaas). Construye tu propio formulario de tarjeta, luego new Unipaas().initTokenize(sessionToken, fields, options). Los campos seguros son una característica de este paquete, no un paquete separado.
2. Embebidos web del comprador — carga https://cdn.unipaas.com/embedded-ui.js, luego unipaas.buyerComponents(sessionToken, config) y .create("checkout"|"card"|"digitalWallet").mount("#id").

Límite de autenticación (importante):

• Pago del comprador (campos seguros y embebidos web del comprador) → sessionToken de POST /pay-ins/checkout.
• Embebidos de plataforma (unipaas.components: saldo, factura, incorporación, portal de pago, notificación) → el token de acceso /authorize con scopes + vendorId. El checkout del comprador no usa el token de acceso /authorize.

Después de cualquier autorización del lado del cliente, verifica del lado del servidor con GET /pay-ins/{authorizationId}; el estado debe ser CAPTURED para éxito.

Referencias

• references/auth.md — el flujo /authorize, ámbitos, ciclo de vida del token, idempotencia.
• references/accept-payments.md — el producto de Aceptar Pagos, los tres niveles, la Página de Pago, creación de pago, tokenización, webhooks.
• references/web-sdk.md — las dos rutas de pago del comprador del lado del cliente alimentadas por sessionToken.
• references/security.md — manejo de claves, qué permanece en el servidor, la superficie PCI.