# SolintPay — Contexto COMPLETO de integración (llms-full.txt) > Todo lo necesario para integrar SolintPay está en este archivo: > (1) la guía de integración paso a paso y (2) la especificación OpenAPI 3.1 > completa (fuente de verdad de la API). Base URL: https://solintpay.vercel.app ═══════════════════ PARTE 1 · GUÍA DE INTEGRACIÓN ═══════════════════ # Guía de integración con SolintPay Esta es la guía que un desarrollador de un comercio (PadelBox, una clínica, un e-commerce, etc.) sigue para integrar **SolintPay** en su sistema y empezar a cobrar por Pago Móvil. > **Tiempo estimado:** 2-4 horas para una integración completa con webhooks. > > **Cómo usar esta guía:** está escrita pensando en **producción**. Intégrala > usando los valores de ejemplo (los `placeholders` tipo `sk_test_TU_KEY`), y > cuando SolintPay te entregue tus credenciales reales, **solo las reemplazas** — > tu código no cambia. --- ## 1. Lo que SolintPay te entrega Antes de escribir una línea de código, SolintPay te da estas cosas: | Dato | Formato | Para qué | |---|---|---| | **API key de prueba** | `sk_test_…` | Integrar y probar en el sandbox sin mover dinero real | | **API key de producción** | `sk_live_…` | Cobros reales — te la damos al aprobar tu registro (KYC) | | **URL base del API** | La que te confirme SolintPay (hoy: `https://solintpay.vercel.app`) | A dónde apuntan todas tus llamadas | | **Webhook secret** | `whsec_…` | Verificar que las notificaciones vienen de verdad de SolintPay — te lo damos cuando registras tu webhook | ### ¿Cómo obtienes tu API key? (autoservicio, 2 minutos) 1. Entra a **`https://solintpay.vercel.app/panel/registro`**, crea tu cuenta con el RIF de tu empresa y acepta los términos. **Recibes tu `sk_test_…` al instante** (en pantalla y por correo) — no tienes que hablar con nadie. 2. Integras y pruebas con ella en el sandbox (no mueve dinero real). 3. Tu panel te muestra el **"Camino a producción"**: qué documentos subir (KYC: RIF + cédula del dueño, en **Verificación**) y qué dato pedirle a tu banco (el ChildClientID del BNC). Cuando esté todo, SolintPay activa tu **modo producción** y tu key empieza a cobrar de verdad. > Si eres el programador del comercio: **pídele al dueño la API key** (la ve en su > panel → API Keys, donde también puede generar otra). No se genera desde el > código ni desde esta guía. > 💡 **¿Necesitas cobrar antes de integrar?** El dueño del comercio ya tiene su > **panel** (`/panel`): ahí puede cobrar directo desde **Cobrar (POS)** sin > escribir código, ver todas sus transacciones, confirmar pagos Zelle, gestionar > API keys y webhooks, y seguir el **"Camino a producción"** — un checklist que > le dice exactamente qué dato le falta para operar con dinero real. Esta guía es > para conectar **tu sistema o tu app** a ese mismo motor. > > La clave se muestra **una sola vez** y se guarda **cifrada** (hash); SolintPay no > puede recuperarla después. Si se pierde, se genera una nueva (rotación). > 🔒 **Tu API key y tu webhook secret son SECRETOS.** Guárdalos en variables de > entorno (`SOLINTPAY_API_KEY`, `SOLINTPAY_WEBHOOK_SECRET`), **nunca** en el > código fuente, en el repositorio ni en el frontend. Ver la sección > [🔒 Seguridad](#-seguridad). Para que los ejemplos de abajo se copien y peguen fácil, define estas dos variables en tu terminal: ```bash export BASE="https://solintpay.vercel.app" # URL base que te dio SolintPay export KEY="sk_test_TU_KEY" # tu API key (de prueba primero) ``` --- ## 2. Probar conectividad (10 min) Primero confirma que tu API key funciona: ```bash curl -H "Authorization: Bearer $KEY" "$BASE/v1/ping" ``` Esperado: ```json { "ok": true, "cliente": "Tu Comercio", "env": "test", "timestamp": "..." } ``` El campo `env` te dice si estás en `test` (sandbox) o `live` (producción), según el tipo de API key que usaste. --- ## 3. Hacer un cobro (30 min) Un cobro C2P (Cliente-a-Persona) funciona así: el cliente final te **dicta** su cédula, su teléfono, su banco y un **Token** que él generó en la app de su banco. Con esos datos, SolintPay le debita al instante. > ⚠️ **Esos 4 datos del cliente son entrada dinámica** — los recibes de tu cliente > en el momento de pagar (desde tu formulario, tu POS, etc.). **No los > hardcodees.** Para *probar* en sandbox hay datos de ejemplo en el > [🧪 Apéndice: Modo de prueba](#-apéndice-modo-de-prueba-sandbox). ```bash curl -X POST "$BASE/v1/cobros" \ -H "Authorization: Bearer $KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "metodo": "c2p_bnc", "monto": 25.50, "moneda": "VES", "cliente": { "cedula": "V12345678", "telefono": "584141234567", "banco": "0102", "token": "1234567" }, "referencia_externa": "RESERVA-001", "concepto": "Cancha 1 - 18:00" }' ``` > El header `Idempotency-Key` (un UUID único por intento) evita cobros duplicados > si tu red falla y reintentas. Es opcional pero **muy recomendado** en POSTs. ### Respuesta exitosa ```json { "id": "cobr_KFt7ZiohxTjaBSTS", "estado": "exitoso", "metodo": "c2p_bnc", "monto": 25.50, "moneda": "VES", "proveedor": { "nombre": "bnc", "id_transaccion": 442350, "referencia": "036626" }, "creado_en": "2026-06-03T15:58:13.103Z" } ``` ### Respuesta rechazada ```json { "id": "cobr_xxx", "estado": "rechazado", "error": "fondos_insuficientes", "codigo": "G51", "codigo_completo": "ECBG51", "mensaje": "El cliente no tiene fondos suficientes" } ``` Códigos de error frecuentes en un cobro: - `token_incorrecto` — Token mal o expirado. El token del cliente expira a las 11:59 PM del día que lo generó. - `fondos_insuficientes` — El cliente no tiene saldo. - `no_afiliado` — El cliente no está afiliado a Pago Móvil. - `cedula_invalida` — Cédula con formato o dígito errado. - `limite_excedido` — El cliente excedió su monto diario. --- ## 3b. Cobrar con tarjeta internacional — `stripe_card` (15 min) Para clientes con tarjeta internacional (Visa/Mastercard, monedas `USD, EUR, GBP, BRL, MXN, COP`). El flujo es distinto al C2P: **no es débito inmediato**, sino un checkout alojado — creas el cobro, rediriges a tu cliente a `checkout_url`, y el resultado te llega por webhook. ```bash curl -X POST "$BASE/v1/cobros" \ -H "Authorization: Bearer $KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "metodo": "stripe_card", "monto": 25.00, "moneda": "USD", "cliente": { "email": "cliente@ejemplo.com" }, "referencia_externa": "RESERVA-002", "concepto": "Cancha 2 - 19:00" }' ``` Respuesta (`201`): ```json { "id": "cobr_xxx", "estado": "pendiente_pago", "metodo": "stripe_card", "monto": 25.00, "moneda": "USD", "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...", "proveedor": { "nombre": "stripe", "session_id": "cs_test_...", "expira_en": 1780000000 }, "creado_en": "..." } ``` **Qué haces tú:** redirige a tu cliente a `checkout_url` (o ábrelo en una ventana). Cuando pague, Stripe confirma y el estado del cobro pasa a `exitoso` — te enteras por webhook o consultando `GET /v1/cobros/{id}` (el GET también devuelve el `checkout_url` mientras el cobro sigue `pendiente_pago`, por si necesitas reenviárselo al cliente). **¿A dónde vuelve el cliente después de pagar?** Por defecto, a la página de resultado de SolintPay (`/pay/{id}?status=success` o `?status=cancel`). Si prefieres que vuelva a TU app (lo normal en una app de reservas), pasa tus propias URLs `https` al crear el cobro: ```json { "metodo": "stripe_card", "monto": 25.00, "moneda": "USD", "success_url": "https://tu-app.com/reserva/123/pagada", "cancel_url": "https://tu-app.com/reserva/123/cancelada" } ``` > - `cliente` es opcional aquí (solo `email`, para el recibo de Stripe). > - El cobro usa **la cuenta Stripe del comercio** (configuras tu Secret Key en el > panel). Si no está configurada: `412 stripe_no_configurado`. > - Stripe no liquida a Venezuela: este método es para comercios con cuenta Stripe > propia (entidad fuera de VE) que venden a clientes internacionales. --- ## 3c. Cobrar por Zelle o con confirmación manual (15 min) Para pagos que **un humano del comercio verifica y confirma** (Zelle, o comprobante por WhatsApp/transferencia). El cobro nace en `estado: "pendiente_confirmacion"` y pasa a `exitoso` cuando el comercio lo confirma desde su panel. ```bash curl -X POST "$BASE/v1/cobros" \ -H "Authorization: Bearer $KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "metodo": "zelle", "monto": 30.00, "moneda": "USD", "instrucciones": { "zelle_email": "pagos@tucomercio.com", "titular": "Tu Comercio LLC", "nota": "Indica la referencia en el memo" }, "referencia_externa": "RESERVA-003" }' ``` Respuesta (`201`): `estado: "pendiente_confirmacion"` + `checkout_url` — una página alojada que muestra a tu cliente **a dónde enviar el Zelle** y la referencia. La página se actualiza sola cuando el comercio confirma. **El ciclo completo:** 1. Creas el cobro → muestras/rediriges al `checkout_url` (o muestras las instrucciones tú mismo). 2. Tu cliente envía el Zelle y avisa. 3. El dueño del comercio verifica en su banco → panel → **Transacciones** → botón **Confirmar** (o Rechazar). 4. El cobro pasa a `exitoso` y te llega el webhook `cobro.confirmado`. > - `metodo: "manual"` funciona igual pero sin campos de Zelle: pasa la > instrucción libre en `instrucciones.nota` (ej. "envía el comprobante por WhatsApp al 0414..."). > - Para `zelle`, `instrucciones.zelle_email` es **requerido** (400 si falta). ### Binance Pay — próximamente `metodo: "binance_pay"` ya existe en el API pero está deshabilitado hasta activar las credenciales: hoy responde `503 metodo_no_disponible`. Tu código puede manejarlo desde ya con ese error. --- ## 4. Mostrar la tasa BCV en tu UI (5 min) Si vendes en USD pero cobras en bolívares, muestra el equivalente al BCV: ```bash curl -H "Authorization: Bearer $KEY" "$BASE/v1/tasa-bcv" ``` ```json { "tasa": 36.6642, "moneda_base": "USD", "moneda_destino": "VES", "fecha": "07/08/2024" } ``` > En sandbox la tasa siempre es un valor fijo de prueba. En producción se > actualiza con el BCV real cada día. **¿Cotizas en dólares y también usas tasa paralelo?** `GET /v1/tasas` devuelve ambas (`bcv` en vivo + `paralelo` si SolintPay la tiene configurada). Y mejor aún: puedes **fijar el precio en Bs al momento de cobrar** sin calcular nada — en vez de `monto`, envía `monto_usd` + `tasa_tipo`: ```json { "metodo": "c2p_bnc", "monto_usd": 10, "tasa_tipo": "bcv", "cliente": { "cedula": "...", "telefono": "...", "banco": "...", "token": "..." } } ``` La respuesta trae el `monto` en Bs calculado, más `monto_usd`, `tasa_tipo` y `tasa_aplicada` para tu contabilidad. Si la tasa paralelo no está configurada: `400 tasa_no_disponible`. --- ## 5. Registrar tu webhook (15 min) Aquí está la magia: cada vez que entre un pago a tu cuenta, SolintPay te avisa con una notificación HTTP (webhook) firmada. **¿Cómo se "activa"?** No hay interruptor: el webhook queda activo en el momento en que registras una URL `https://` válida (panel → Webhooks, o `POST /v1/webhooks`). Desde ahí SolintPay envía un `POST` a esa URL cada vez que ocurre uno de estos eventos: | Evento | Cuándo se dispara | |---|---| | `pago.recibido` | El BNC avisa que entró un Pago Móvil o transferencia a tu cuenta (requiere que el banco tenga activadas las notificaciones push para tu comercio; SolintPay lo gestiona en la certificación). | | `cobro.confirmado` | Un cobro creado por API pasa a `exitoso` por un camino **asíncrono**: tarjeta (Stripe), Binance Pay o confirmación manual desde el panel. | | `webhook.test` | Solo cuando pulsas "Enviar prueba" en el panel o llamas `POST /v1/webhooks/test`. | Los cobros C2P por Pago Móvil (`c2p_bnc`) se resuelven en la misma llamada `POST /v1/cobros`: la respuesta ya trae `estado: "exitoso"`, así que no hace falta esperar webhook para ellos. El primer intento de entrega es inmediato. Si tu servidor no responde 2xx en 10 segundos se reintenta con espera creciente (30 s, 2 min, 10 min, 1 h, 6 h, 24 h) y luego se marca `abandonado`. Cada intento queda en el panel → Webhooks → "Entregas recientes". ### 5.1 Levanta tu endpoint En tu servidor, crea un endpoint `POST` que va a recibir los webhooks. Para probar al principio puedes usar [webhook.site](https://webhook.site) y ver lo que llega. ### 5.2 Registra tu URL en SolintPay > ⚠️ **Requisitos de la URL:** debe ser **`https://`** y apuntar a un **dominio > público**. Se rechazan `http://`, `localhost`, IPs privadas y hosts internos > (medida anti-SSRF). Para probar en local usa un túnel https (ngrok, > Cloudflare Tunnel) o [webhook.site](https://webhook.site). **La forma fácil (recomendada):** el **dueño del comercio** entra a su panel → sección **Webhooks**, registra la URL y copia el `whsec_…` que se muestra una sola vez. Si eres el programador contratado, pídele al dueño ese `whsec_…` — es lo único que necesitas de él para esta sección. **Por API con tu misma API key** (lo más directo si estás programando): ```bash curl -X POST "$BASE/v1/webhooks" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://tu-servidor.com/webhooks/solintpay", "eventos": ["pago.recibido", "cobro.confirmado"] }' ``` Y cuando tengas tu endpoint listo, pruébalo con un evento firmado de verdad: ```bash curl -X POST "$BASE/v1/webhooks/test" -H "Authorization: Bearer $KEY" # → { "url": "...", "respuesta_status": 200, "respuesta_ok": true, "latencia_ms": 184 } ``` **Alternativa desde el panel por API** (mismo resultado), con las **credenciales humanas** del panel (correo y contraseña del dueño): ```bash # 1. Login con tus credenciales humanas LOGIN=$(curl -s -X POST "$BASE/admin/login" \ -H "Content-Type: application/json" \ -d '{"email":"TU_EMAIL","password":"TU_PASSWORD"}') # 2. Saca el access_token ACCESS=$(echo $LOGIN | jq -r .tokens.access_token) # 3. Registra el webhook curl -X PUT "$BASE/admin/webhook" \ -H "Authorization: Bearer $ACCESS" \ -H "Content-Type: application/json" \ -d '{ "url": "https://tu-servidor.com/webhooks/solintpay", "eventos": ["pago.recibido", "cobro.confirmado"] }' ``` Respuesta: ```json { "id": "...", "url": "https://tu-servidor.com/webhooks/solintpay", "secret": "whsec_xxxxxxxxxxxx", "creado_en": "..." } ``` > ⚠️ **Guarda ese `secret`** (`whsec_…`) en una variable de entorno > (`SOLINTPAY_WEBHOOK_SECRET`). **No se muestra de nuevo.** ### 5.3 Verifica la firma HMAC del lado tuyo Cuando recibes un webhook, **DEBES verificar la firma** para confirmar que viene de SolintPay y no de un impostor. Ejemplo en Node.js: ```javascript import crypto from 'crypto'; import express from 'express'; const app = express(); // IMPORTANTE: necesitamos el body crudo para verificar la firma. app.use('/webhooks/solintpay', express.raw({ type: 'application/json' })); app.post('/webhooks/solintpay', async (req, res) => { const secret = process.env.SOLINTPAY_WEBHOOK_SECRET; const signatureHeader = req.headers['x-solintpay-signature']; // "sha256=" const rawBody = req.body; // Buffer const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex'); // Comparación segura contra ataques de tiempo if (signatureHeader.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))) { return res.status(401).json({ error: 'firma_invalida' }); } // ✓ Webhook legítimo const event = JSON.parse(rawBody.toString()); const deliveryId = req.headers['x-solintpay-delivery-id']; // IDEMPOTENCIA: guarda el deliveryId; si ya lo procesaste, no lo proceses de nuevo if (await yaLoProcesamos(deliveryId)) { return res.json({ ok: true, replay: true }); } // Procesa el evento if (event.evento === 'pago.recibido') { const { monto, moneda, referencia_bnc, cliente, fecha } = event.datos; // Marca la reserva como pagada, envía confirmación al cliente, etc. } await guardarComoProcesado(deliveryId); res.json({ ok: true }); }); ``` ### 5.4 Headers que trae cada webhook | Header | Para qué | |---|---| | `X-SolintPay-Event` | Nombre del evento (`pago.recibido`, etc.) | | `X-SolintPay-Signature` | Firma HMAC, formato `sha256=` | | `X-SolintPay-Delivery-Id` | UUID del envío — úsalo para idempotencia | | `X-SolintPay-Attempt` | Número de intento (1 a 7) | ### 5.5 Payload del webhook ```json { "id": "delivery_uuid", "evento": "pago.recibido", "creado_en": "2026-06-03T15:58:16Z", "intento": 1, "datos": { "tipo": "P2P", "monto": 1500.00, "moneda": "0928", "referencia_bnc": "DBR-xxx", "referencia_banco_origen": "OBR-xxx", "banco_origen": "0102", "fecha": "20260603", "hora": "1430", "cliente": { "cedula": "V12345678", "telefono": "00584241234567", "concepto": "Reserva cancha" } } } ``` > Nota: en el payload del webhook, `moneda` llega como el **código ISO 4217 > numérico** que usa el banco (`0928` = bolívar VES), no como el string `"VES"`. ### 5.6 Reintentos Si no respondes `2xx` en 10 segundos, SolintPay reintenta con backoff: **30s, 2 min, 10 min, 1h, 6h, 24h** — hasta 7 intentos. Después abandona. Por eso es crítico responder rápido y procesar **después** (en background). --- ## 6. Listar y consultar tus cobros (10 min) ```bash # Listar (filtros opcionales) curl -H "Authorization: Bearer $KEY" \ "$BASE/v1/cobros?limit=20&estado=exitoso" # Detalle de uno curl -H "Authorization: Bearer $KEY" \ "$BASE/v1/cobros/cobr_XYZ" ``` --- ### 6b. Comprobante electrónico del cobro Todo cobro **exitoso** tiene un comprobante con los datos que exige la normativa bancaria (afiliado, fecha/hora, autorización del banco, monto, referencia, teléfonos y cédula **enmascarados**). Puedes mostrarlo al cliente o imprimirlo en tu propio recibo: ```bash # Página lista para mostrar/imprimir (pública, sin API key: solo quien tiene el id) https://solintpay.vercel.app/pay/cobr_XYZ/comprobante # Los mismos datos en JSON, para armar tu recibo curl "$BASE/pay/cobr_XYZ/comprobante?formato=json" ``` Responde `409 sin_comprobante` si el cobro no está en estado `exitoso`. --- ## 7. Reversar un cobro (10 min) El mismo endpoint reversa según el método: **reverso C2P** en el banco para `c2p_bnc`, o **refund total en Stripe** para `stripe_card`. Si el cliente reclama o hubo un error: ```bash curl -X POST "$BASE/v1/cobros/cobr_XYZ/reversar" \ -H "Authorization: Bearer $KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "motivo": "Cliente reclamó" }' ``` --- ## 8. Referencia completa de endpoints Todas las llamadas requieren el header `Authorization: Bearer `. Base URL: la que te confirme SolintPay. Todos los `POST` aceptan el header opcional `Idempotency-Key` (UUID v4 o string único de 8-64 caracteres). ### Catálogo #### `GET /v1/ping` Verifica conectividad y validez de tu API key. Respuesta: `{ ok, cliente, env, timestamp }`. #### `GET /v1/bancos` Lista de bancos venezolanos con sus códigos oficiales del BCV (`0102` = Banco de Venezuela, `0191` = BNC, etc.). Respuesta: `{ data: [ { codigo, nombre, servicios } ] }`. #### `GET /v1/tasa-bcv` Tasa BCV oficial del día. Respuesta: `{ tasa, moneda_base, moneda_destino, fecha }`. #### `GET /v1/tasas` BCV (en vivo) + paralelo (si SolintPay la configuró). Respuesta: `{ bcv: { tasa, fecha }, paralelo: { tasa, actualizada_en } | null }`. ### Cobros #### `POST /v1/cobros` Primitiva única de cobro. `metodo` decide el rail: `c2p_bnc` (Pago Móvil, débito inmediato — requiere `cliente` completo; acepta `monto_usd` + `tasa_tipo` para fijar el precio en Bs), `vpos_bnc` (tarjeta nacional de débito/crédito por punto de venta — requiere objeto `tarjeta`), `stripe_card` (tarjeta internacional — devuelve `checkout_url`, sección 3b), `zelle` / `manual` (confirmación del comercio — sección 3c) o `binance_pay` (próximamente, 503). El ejemplo siguiente es C2P: el cliente te dicta sus datos y el token de su app. Body: ```json { "metodo": "c2p_bnc", "monto": 25.50, "moneda": "VES", "cliente": { "cedula": "V12345678", "telefono": "584141234567", "banco": "0102", "token": "1234567" }, "referencia_externa": "RESERVA-001", "concepto": "Cancha 1 - 18:00" } ``` Campos requeridos: `metodo`, `monto`, `cliente` (con `cedula`, `telefono`, `banco`, `token`). Respuesta `201`: objeto `Cobro`. Rechazo del banco: `422` con `{ error, codigo, codigo_completo, mensaje }`. #### `GET /v1/cobros` Lista tus cobros. Query: `limit` (default 20, máx 100), `estado` (`iniciado` | `exitoso` | `rechazado` | `error`). #### `GET /v1/cobros/{id}` Detalle de un cobro. `404` si no existe o no es tuyo. #### `POST /v1/cobros/{id}/reversar` Reversa un cobro **exitoso**. Body opcional: `{ "motivo": "..." }`. `400` si el cobro no es reversable. ### Pagos #### `POST /v1/pagos` Tu comercio paga a un beneficiario (P2P). Útil para devoluciones, cashback o payouts. Body: ```json { "metodo": "p2p_bnc", "monto": 50.00, "moneda": "VES", "beneficiario": { "cedula": "V12345678", "telefono": "584141234567", "banco": "0102", "nombre": "Juan Pérez", "email": "juan@ejemplo.com" }, "concepto": "Devolución reserva", "referencia_externa": "DEV-001" } ``` Requeridos: `metodo`, `monto`, `beneficiario` (con `cedula`, `telefono`, `banco`, `nombre`). ### Cuenta #### `GET /v1/cuenta/saldo` Saldo de tus cuentas bancarias. Respuesta: `{ data: [ { numero, moneda, saldo } ] }`. #### `GET /v1/cuenta/movimientos` Movimientos de una cuenta. Query: `cuenta` (requerido), `desde` y `hasta` (fechas opcionales, formato `YYYY-MM-DD`). ### Verificación #### `POST /v1/pagos/verificar` Verifica si un pago realmente entró (cuando el cliente dice "ya te pagué pero no me llega notificación"). Body: ```json { "tipo": "p2p", "cuenta_propia": "0191...", "monto": 25.50, "referencia": "036626", "fecha": "2026-06-03", "telefono_pagador": "584141234567", "banco_pagador": "0102" } ``` Requeridos: `tipo` (`p2p` | `referencia`), `cuenta_propia`, `monto`, `referencia`, `fecha`. Respuesta: `{ encontrado: boolean, detalle: object | null }`. --- ## 📱 Integración desde una app móvil (iOS / Android / React Native / Flutter) La regla de oro: **la app NUNCA habla directo con SolintPay.** Tu API key (`sk_test_` / `sk_live_`) solo puede vivir en **tu backend** — cualquier string embebido en un APK/IPA se puede extraer descompilando la app. ``` App móvil ──▶ TU backend ──▶ SolintPay ──▶ Banco ▲ │ └── respuesta ◀───┘ (y los webhooks de SolintPay llegan a TU backend) ``` **El flujo correcto para un cobro C2P desde la app:** 1. La app muestra tu formulario de pago: cédula, teléfono, banco (usa `GET /v1/bancos` **vía tu backend** para el selector) y el **token** que el cliente genera en la app de su banco. 2. La app manda esos 4 datos a **tu backend** (tu propio endpoint, con tu propia autenticación de usuarios). 3. Tu backend llama `POST /v1/cobros` con tu API key y un `Idempotency-Key`. 4. Tu backend devuelve el resultado a la app (`exitoso` / `rechazado` + mensaje amigable del campo `mensaje`). 5. Para métodos con checkout (`stripe_card`, `zelle`): tu backend recibe el `checkout_url` y la app lo abre en un **navegador in-app** (SFSafariViewController / Chrome Custom Tabs / `Linking.openURL`). La confirmación te llega por **webhook a tu backend**, no a la app — la app se entera consultando tu backend (polling o push propio). **Qué NO hacer en la app:** - ❌ Incluir la API key en el código, en un `.env` bundleado o en remote config. - ❌ Llamar `https://solintpay.vercel.app/v1/...` directo desde la app. - ❌ Confiar en el resultado que reporta la app: el estado real del cobro es el que ve tu backend (webhook o `GET /v1/cobros/{id}`). **Tip UX móvil:** el token C2P lo genera el cliente en la app de su banco y expira el mismo día — pon el campo token de último en el formulario y permite reintentar con `token_incorrecto` sin perder los demás datos. --- ## 🔒 Seguridad Qué es secreto y qué no, para que no expongas nada sin querer: | Dato | ¿Secreto? | Regla | |---|---|---| | API key (`sk_test_` / `sk_live_`) | **SÍ** | Solo en el backend, en variables de entorno. Nunca en el frontend, el repo ni logs. | | Webhook secret (`whsec_…`) | **SÍ** | Solo en el backend. Es lo que te permite confiar en los webhooks. | | Contraseña del panel admin | **SÍ** | Nunca la pongas en código. | | URL base del API | No | Es pública, la necesita tu servidor. | | IDs de cobro (`cobr_…`), referencias | No | Son identificadores, no credenciales. | Buenas prácticas: - **Verifica SIEMPRE la firma HMAC** de cada webhook (sección 5.3). Sin eso, cualquiera podría enviarte pagos falsos. - **Sé idempotente** con el `X-SolintPay-Delivery-Id` para no procesar dos veces el mismo pago. - Si crees que tu API key se filtró, avísanos para **rotarla** de inmediato. --- ## 🧪 Apéndice: Modo de prueba (sandbox) Mientras integras, usa una API key `sk_test_…`. En sandbox **ninguna operación mueve dinero real** — todo es una simulación contra el ambiente de calidad del banco. Para hacer un **cobro de prueba** necesitas datos de un cliente. El banco tiene una identidad de prueba registrada en su sandbox; usa estos valores: ```json { "cedula": "V23000760", "telefono": "584242207524", "banco": "0191", "token": "9982783" } ``` > ⚠️ **Estos son datos de prueba del sandbox del banco — NO son de un cliente > real y solo funcionan en el ambiente de prueba.** En producción, estos cuatro > campos los recibes de tu cliente real en el momento de cobrar (el token lo > genera él en la app de su banco). > > **Cómo trata el sandbox tus cobros:** el comercio en **modo sandbox** hace que > el banco **valide** cada operación (formato, cripto, datos) pero **no la > ejecute**. Por eso el token fixture de arriba funciona y el cobro sale > `exitoso` sin mover dinero. Si en sandbox te devuelve `token_incorrecto` con > los fixtures, casi siempre es porque tu comercio quedó en **modo producción** > (ahí el banco sí ejecuta y exige un token real del cliente) — pídele a SolintPay > que lo devuelva a sandbox (consola de operador → el comercio → *Volver a > sandbox*). > > En sandbox el banco a veces **no emite `proveedor.referencia`** (puede venir > `null`) ni `id_transaccion` reversable, aunque el cobro salga `exitoso`. En > producción sí vienen siempre — no dependas de ellos para tus pruebas de sandbox. --- ## 🚀 Paso a producción **Concepto clave:** el ambiente lo decide el **modo del comercio**, no tu código. - **Sandbox** → el banco **valida** los cobros pero **no los ejecuta**. Usas los fixtures, nada mueve dinero. Es donde integras y pruebas. - **Producción** → los cobros se **ejecutan** de verdad: el cliente pone su token real (o su tarjeta) y el dinero cae en la cuenta del comercio. Pasar de uno a otro es eficiente y no requiere reescribir la integración. Hay dos lados: **Del lado de SolintPay (consola de operador → ficha del comercio):** 1. Aprobar el **KYC** del comercio. 2. En **Configuración de cobro**, cargar el **ChildClientID** del BNC del comercio (así el dinero cae en SU cuenta, no en la de SolintPay). Sin él, no deja activar producción. 3. **Activar producción**. Se puede **Volver a sandbox** en cualquier momento para seguir probando — el mismo comercio, sin perder su configuración ni sus keys. **Del lado del integrador (tú) — tu código NO cambia:** 1. Cambia la API key `sk_test_…` → `sk_live_…` en `SOLINTPAY_API_KEY`. **La key decide el ambiente**; el resto del código es idéntico. 2. Usa **datos reales del cliente** (el token lo genera él en la app de su banco), en vez de los fixtures del sandbox. 3. **Registra tu webhook de producción** apuntando a tu URL real y guarda el nuevo `whsec_…`. 4. A partir de ahí, los cobros **mueven dinero real**. --- ## 📦 SDKs oficiales Si prefieres no escribir el HTTP a mano, hay SDKs con la misma superficie (crear/consultar/listar/reversar + verificación HMAC de webhooks incluida): | Lenguaje | Dónde | Nota | |---|---|---| | **Node.js** | `sdk/` del repo (npm `solintpay`) | Con tipos TypeScript, sin dependencias (Node ≥18) | | **Python** | `sdk/python/solintpay.py` | Un solo archivo, stdlib pura (≥3.8) | | **PHP** | `sdk/php/SolintPay.php` | Un solo archivo, cURL (≥7.4) | ```js const { SolintPay } = require('solintpay'); const sp = new SolintPay({ apiKey: process.env.SOLINTPAY_API_KEY }); const cobro = await sp.crearCobro({ metodo: 'c2p_bnc', monto: 25.5, moneda: 'VES', cliente: { ... } }); ``` --- ## 🐞 Troubleshooting | Problema | Causa más común | |---|---| | `401 unauthorized` | Olvidaste el header `Authorization` | | `401 invalid_api_key` | API key inválida o revocada | | `403 insufficient_scope` | Tu API key no tiene el scope `cobros:create` | | `422 token_incorrecto` | Token del cliente errado o expirado (renovar) | | `422 fondos_insuficientes` | El cliente no tiene saldo | | `409 idempotency_conflict` | Reusaste un `Idempotency-Key` con un body distinto | | `5xx` | Error de nuestro lado — avísanos | --- ## 📞 Soporte - Email: soporte@solintpay.com - Status: https://status.solintpay.com (próximamente) ═══════════════════ PARTE 2 · OPENAPI 3.1 (fuente de verdad) ═══════════════════ ```yaml openapi: 3.1.0 info: title: SolintPay API version: '1.0.0' description: | **SolintPay** es la pasarela de pagos para comercios venezolanos. Esta API permite a tu sistema cobrar, pagar, consultar saldos y recibir notificaciones de pagos en tiempo real — sin tener que integrarte directamente con los bancos. **Bancos soportados actualmente:** BNC (Banco Nacional de Crédito). Próximamente: Bancaribe, Mercantil, Banesco. ## Autenticación Todas las llamadas requieren un header `Authorization: Bearer `. La API key tiene formato `sk_test_…` (sandbox) o `sk_live_…` (producción). En BETA, SolintPay te entrega tu API key de sandbox al registrar tu comercio; puedes generar claves adicionales desde tu [panel](https://solintpay.vercel.app/panel) (sección **API Keys**). La clave cruda solo se muestra **una vez** al generarla. ## Idempotencia En todos los endpoints `POST`, puedes enviar un header `Idempotency-Key` con un UUID v4 (o cualquier string único de 8-64 chars alfanuméricos). Si el mismo request se reenvía con la misma key, devolvemos el resultado cacheado. Útil para que los reintentos en redes inestables NO generen cobros duplicados. ## Webhooks Cuando entra un pago a tu cuenta, te lo notificamos por webhook firmado con HMAC-SHA256. Configuras tu URL desde tu panel (sección **Webhooks**) o vía `PUT /admin/webhook`. Cada webhook trae: - `X-SolintPay-Event` — nombre del evento (`pago.recibido`, etc) - `X-SolintPay-Signature` — firma HMAC formato `sha256=` - `X-SolintPay-Delivery-Id` — UUID del envío (para idempotencia tuya) - `X-SolintPay-Attempt` — número de intento (1-7) Verificas la firma en tu servidor con el `secret` que te dimos al registrar el webhook. ## Códigos de error comunes | Código | Significado | |---------------|----------------------------------------------| | `validacion` | Algún campo del body no pasa validación | | `unauthorized`| Falta o es inválido el Bearer | | `invalid_api_key` | API key revocada o no existe | | `insufficient_scope` | API key sin el scope necesario | | `token_incorrecto` | Token C2P del cliente incorrecto/expirado | | `fondos_insuficientes` | El cliente no tiene saldo | | `no_afiliado` | Beneficiario no afiliado a Pago Móvil | | `limite_excedido` | Excede límite diario | | `proveedor_error` | Error del banco (con `codigo_completo`) | | `metodo_no_disponible` | El método existe pero no está habilitado aún (ej. binance_pay) | | `stripe_no_configurado` | Falta la Stripe Secret Key del comercio (para stripe_card) | contact: email: soporte@solintpay.com license: name: Propietario servers: - url: https://solintpay.vercel.app description: Producción - url: http://localhost:3000 description: Local (desarrollo) security: - bearerAuth: [] tags: - name: Catálogo description: Datos públicos del sistema (bancos, tasa BCV) - name: Cobros description: Cobrar a clientes vía Pago Móvil C2P - name: Pagos description: Tu comercio paga a un beneficiario (P2P) - name: Cuenta description: Consultar saldo y movimientos de tus cuentas - name: Webhooks description: Configuración de notificaciones salientes - name: Verificación description: Verificar si un pago entró sin cobrar paths: /v1/ping: get: tags: [Catálogo] summary: Verificar conectividad y validez de la API key responses: '200': description: OK content: application/json: schema: type: object properties: ok: { type: boolean, example: true } cliente: { type: string, example: "PadelBox Demo" } env: { type: string, enum: [test, live] } timestamp: { type: string, format: date-time } /v1/bancos: get: tags: [Catálogo] summary: Lista de bancos venezolanos description: Códigos oficiales del BCV (0102 = Banco de Venezuela, 0191 = BNC, etc.) responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: codigo: { type: string, example: "0191" } nombre: { type: string, example: "Banco Nacional de Crédito" } servicios: type: array items: { type: string, example: "TRF" } /v1/tasas: get: tags: [Catálogo] summary: Tasas USD→VES (BCV en vivo + paralelo configurada) responses: '200': description: OK content: application/json: schema: type: object properties: bcv: type: object nullable: true properties: tasa: { type: number, example: 36.6642 } fecha: { type: string, example: "07/08/2024" } paralelo: type: object nullable: true properties: tasa: { type: number, example: 38.2 } actualizada_en: { type: string, format: date-time } /v1/tasa-bcv: get: tags: [Catálogo] summary: Tasa BCV oficial del día responses: '200': description: OK content: application/json: schema: type: object properties: tasa: { type: number, example: 36.6642 } moneda_base: { type: string, example: "USD" } moneda_destino: { type: string, example: "VES" } fecha: { type: string, example: "07/08/2024" } /v1/cobros: post: tags: [Cobros] summary: Crear un cobro (C2P Pago Móvil, tarjeta internacional o Binance Pay) description: | Primitiva única de cobro. El campo `metodo` decide el rail: - **`c2p_bnc`** — Pago Móvil C2P vía BNC. Requiere `cliente` (cédula, teléfono, banco y token que el cliente genera en su app). Débito inmediato: la respuesta ya trae `estado: exitoso` o el rechazo del banco (422). - **`vpos_bnc`** — Tarjeta nacional de débito/crédito por punto de venta (BNC). Requiere objeto `tarjeta` (número, vencimiento MM/AA, cvv, cédula, titular; pin en débito). Débito inmediato como C2P. PCI: número/cvv/pin solo viajan cifrados al banco, nunca se persisten ni loguean. - **`stripe_card`** — Tarjeta internacional vía Stripe (monedas: USD, EUR, GBP, BRL, MXN, COP). No requiere `cliente` (email opcional). La respuesta trae `estado: pendiente_pago` + `checkout_url`: redirige ahí a tu cliente para pagar; el resultado llega por webhook. Usa la Stripe Secret Key del comercio (configurable en el panel) — 412 si no está configurada. - **`zelle` / `manual`** — Pagos que el comercio verifica y confirma desde su panel. Nacen `pendiente_confirmacion` con `checkout_url` (instrucciones para el cliente). Al confirmarse llega el webhook `cobro.confirmado`. - **`binance_pay`** — Próximamente (hoy responde 503 `metodo_no_disponible`). Para c2p_bnc también puedes cotizar en USD: envía `monto_usd` + `tasa_tipo` (`bcv`|`paralelo`) en vez de `monto` y el precio en Bs se fija al cobrar. parameters: - in: header name: Idempotency-Key required: false schema: { type: string, minLength: 8, maxLength: 64 } requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CrearCobro' responses: '201': description: | Cobro creado. Para `c2p_bnc` viene `estado: exitoso` (débito inmediato). Para `stripe_card` viene `estado: pendiente_pago` + `checkout_url`. content: application/json: schema: { $ref: '#/components/schemas/Cobro' } '422': description: Rechazado por el banco (ver `codigo`) content: application/json: schema: { $ref: '#/components/schemas/ErrorBanco' } '400': description: Validación '401': description: Sin auth '412': description: stripe_no_configurado — falta la Stripe Secret Key del comercio '503': description: metodo_no_disponible — método aún no habilitado (ej. binance_pay) get: tags: [Cobros] summary: Listar tus cobros parameters: - in: query name: limit schema: { type: integer, default: 20, maximum: 100 } - in: query name: estado schema: { type: string, enum: [iniciado, pendiente_pago, exitoso, rechazado, error] } responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: { $ref: '#/components/schemas/Cobro' } /v1/cobros/{id}: get: tags: [Cobros] summary: Detalle de un cobro parameters: - in: path name: id required: true schema: { type: string, example: "cobr_KFt7ZiohxTjaBSTS" } responses: '200': description: OK content: application/json: schema: { $ref: '#/components/schemas/Cobro' } '404': description: No existe o no es tuyo /v1/cobros/{id}/reversar: post: tags: [Cobros] summary: Reversar un cobro exitoso (reverso C2P o refund Stripe según método) parameters: - in: path name: id required: true schema: { type: string } - in: header name: Idempotency-Key schema: { type: string } requestBody: content: application/json: schema: type: object properties: motivo: { type: string, example: "Cliente reclamó" } responses: '201': description: Reverso exitoso '400': description: Cobro no reversable (no exitoso) '404': description: Cobro no existe /v1/pagos: post: tags: [Pagos] summary: Pagar a un beneficiario (P2P) description: Útil para devoluciones, cashback, payouts a freelancers. parameters: - in: header name: Idempotency-Key schema: { type: string } requestBody: required: true content: application/json: schema: type: object required: [metodo, monto, beneficiario] properties: metodo: { type: string, enum: [p2p_bnc] } monto: { type: number, minimum: 0.01 } moneda: { type: string, default: VES } beneficiario: type: object required: [cedula, telefono, banco, nombre] properties: cedula: { type: string, example: "V12345678" } telefono: { type: string, example: "584141234567" } banco: { type: string, example: "0102" } nombre: { type: string, example: "Juan Pérez" } email: { type: string, format: email } concepto: { type: string } referencia_externa: { type: string } responses: '201': { description: Pago exitoso } '422': { description: Rechazado por el banco } /v1/cuenta/saldo: get: tags: [Cuenta] summary: Saldo de tus cuentas bancarias responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: numero: { type: string } moneda: { type: string } saldo: { type: number } /v1/cuenta/movimientos: get: tags: [Cuenta] summary: Movimientos de una cuenta parameters: - in: query name: cuenta required: true schema: { type: string } - in: query name: desde schema: { type: string, format: date } - in: query name: hasta schema: { type: string, format: date } responses: '200': { description: OK } /v1/pagos/verificar: post: tags: [Verificación] summary: Verificar si un pago realmente entró description: | Cuando el cliente dice "ya te pagué pero no me llega notificación", consultá directo al banco. requestBody: required: true content: application/json: schema: type: object required: [tipo, cuenta_propia, monto, referencia, fecha] properties: tipo: { type: string, enum: [p2p, referencia] } cuenta_propia: { type: string } monto: { type: number } referencia: { type: string } fecha: { type: string, format: date } telefono_pagador: { type: string } banco_pagador: { type: string } responses: '200': description: OK content: application/json: schema: type: object properties: encontrado: { type: boolean } detalle: type: object nullable: true /v1/webhooks: post: tags: [Webhooks] summary: Registrar la URL de tu webhook description: | Registra (o reemplaza) la URL donde recibirás las notificaciones de SolintPay. La respuesta incluye el `secret` (`whsec_…`) **una sola vez** — guárdalo para verificar la firma HMAC de cada entrega. **Requisitos de la URL:** debe ser `https://` y apuntar a un dominio público (se rechazan `http://`, `localhost`, IPs privadas y hosts internos). requestBody: required: true content: application/json: schema: type: object required: [url] properties: url: type: string format: uri description: URL https pública que recibirá los POST firmados. example: https://tu-app.com/webhooks/solintpay eventos: type: array items: { type: string } default: [pago.recibido] responses: '201': description: Webhook registrado. El `secret` solo se muestra aquí. content: application/json: schema: type: object properties: id: { type: string } url: { type: string } eventos: { type: array, items: { type: string } } activo: { type: boolean } secret: { type: string, example: whsec_xxxxxxxxxxxx } creado_en: { type: string, format: date-time } '400': description: URL inválida (no https, host privado o interno). get: tags: [Webhooks] summary: Consultar tu webhook activo description: Devuelve la configuración actual (sin el secret). responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object nullable: true properties: id: { type: string } url: { type: string } eventos: { type: array, items: { type: string } } activo: { type: boolean } created_at: { type: string, format: date-time } /v1/webhooks/test: post: tags: [Webhooks] summary: Enviar un evento de prueba a tu webhook description: | Dispara un `webhook.test` firmado a tu URL registrada y devuelve el status y la latencia de tu endpoint. Úsalo para validar tu verificación HMAC antes de recibir pagos reales. responses: '200': description: Resultado del intento de entrega content: application/json: schema: type: object properties: url: { type: string } respuesta_status: { type: integer } respuesta_ok: { type: boolean } latencia_ms: { type: integer } error: { type: string, nullable: true } '400': description: No hay webhook registrado todavía. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: "sk_test_xxx | sk_live_xxx" schemas: CrearCobro: type: object required: [metodo] properties: metodo: type: string enum: [c2p_bnc, stripe_card, zelle, manual, binance_pay] description: | Rail de cobro. c2p_bnc = Pago Móvil (requiere cliente completo). stripe_card = tarjeta internacional (cliente.email opcional). zelle / manual = el comercio confirma el pago (requiere instrucciones.zelle_email para zelle). binance_pay = próximamente (503). monto: type: number minimum: 0.01 description: Requerido salvo que uses monto_usd + tasa_tipo (solo c2p_bnc). monto_usd: type: number description: Solo c2p_bnc — precio en USD; el monto en Bs se fija al cobrar con la tasa elegida. tasa_tipo: type: string enum: [bcv, paralelo] description: Con monto_usd — qué tasa usar (default bcv). instrucciones: type: object description: Solo zelle/manual — lo que verá el cliente en el checkout. properties: zelle_email: { type: string, description: Requerido para zelle. } titular: { type: string } nota: { type: string } moneda: type: string default: VES description: "c2p_bnc: VES. stripe_card: USD/EUR/GBP/BRL/MXN/COP." cliente: type: object description: REQUERIDO para c2p_bnc (cedula, telefono, banco, token). Para stripe_card solo email (opcional). properties: cedula: type: string example: "V12345678" description: Cédula del cliente (V/E/J/G/P + dígitos) telefono: type: string example: "584141234567" description: Teléfono internacional 12 dígitos banco: type: string example: "0102" description: Código del banco (3-4 dígitos) token: type: string example: "1234567" description: Token que el cliente genera en su app email: type: string description: Solo stripe_card (opcional). tarjeta: type: object description: "REQUERIDO para vpos_bnc — tarjeta nacional débito/crédito. PCI: número/cvv/pin solo viajan cifrados al banco, no se persisten." properties: numero: { type: string, description: "Número de la tarjeta" } vencimiento: { type: string, example: "12/28", description: "MM/AA o MMYYYY" } cvv: { type: string } pin: { type: string, description: "Requerido en tarjetas de débito" } cedula: { type: string, example: "V12345678" } titular: { type: string } tipo: { type: string, enum: [debito, credito] } success_url: type: string description: "Solo stripe_card (opcional, https) — a dónde vuelve tu cliente tras pagar. Default: la página de resultado de SolintPay." cancel_url: type: string description: "Solo stripe_card (opcional, https) — a dónde vuelve si cancela." referencia_externa: type: string example: "RESERVA-001" concepto: type: string example: "Reserva cancha 1 - 18:00" Cobro: type: object properties: id: { type: string, example: "cobr_KFt7ZiohxTjaBSTS" } estado: { type: string, enum: [iniciado, pendiente_pago, pendiente_confirmacion, exitoso, rechazado, error] } metodo: { type: string, enum: [c2p_bnc, stripe_card, zelle, manual, binance_pay, c2p_reverso, stripe_refund] } checkout_url: type: string nullable: true description: Solo stripe_card/binance_pay — URL a la que rediriges a tu cliente para pagar. monto: { type: number } moneda: { type: string } cliente: type: object properties: cedula: { type: string, example: "V12345678" } telefono: { type: string, example: "****4567", description: "Enmascarado" } banco: { type: string } proveedor: type: object properties: nombre: { type: string, example: "bnc" } id_transaccion: { type: integer } referencia: { type: string } referencia_externa: { type: string } concepto: { type: string } creado_en: { type: string, format: date-time } ErrorBanco: type: object properties: id: { type: string } estado: { type: string, example: "rechazado" } error: { type: string, example: "token_incorrecto" } codigo: { type: string, example: "G55" } codigo_completo: { type: string, example: "ECBG55" } mensaje: { type: string, example: "El token de pago es incorrecto o expiró" } referencia_externa: { type: string } ```