# PagoLink

> PagoLink es la infraestructura de pagos de Venezuela (un producto de SOFTBIZ). Con una sola integración aceptas todos los métodos del país — Pago Móvil, C2P, Débito Inmediato, Transferencia, Binance Pay, Zelle y PayPal — sin construir cada conexión por separado. El dinero llega directo a la cuenta bancaria del comercio (PagoLink no custodia fondos). Empezamos en Venezuela, construido para escalar al mundo.

Hay dos formas de usarlo: la **API / SDK** para desarrolladores (integrar pagos venezolanos en una app, web o checkout) y el **Terminal POS** para comercios (cobro en persona). El flujo es siempre el mismo: tu backend crea una **sesión**, tu frontend abre el **Checkout** (pago online) o el **Terminal POS** (cobro en persona) con el SDK, y recibes la confirmación por callback. Confirma siempre el estado final del lado del servidor.

Docs completas: https://docs.pagolink.co

## Entornos y dominios

| Servicio | QA (.dev) | Producción (.ai) |
|---|---|---|
| Consola | console.pagolink.co | console.pagolink.softbiz.ai |
| Checkout | pay.pagolink.co | pay.pagolink.softbiz.ai |
| Terminal POS | pos.pagolink.co | pos.pagolink.softbiz.ai |
| API | api.pagolink.co | api.pagolink.co |
| Docs | docs.pagolink.co | docs.pagolink.co |

La API usa prefijos `/v1`, `/accounts/v1` y `/billing/v1`.

Claves: `sk_…` (secreta, SOLO en tu servidor) y `pk_…` (publishable, segura para el frontend).

## 1 · Crear una sesión (backend)

Con tu API key secreta, desde tu servidor:

```
POST https://api.pagolink.co/v1/checkout/sessions   # mismo endpoint para Checkout y Terminal POS
Headers: Content-Type: application/json, x-api-key: sk_live_…
Body: { "amount": 1250.00, "currency": "VES" }
=> { "sessionId": "sess_…" }
```

Ejemplo:

```js
const res = await fetch('https://api.pagolink.co/v1/checkout/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': 'sk_live_…' },
  body: JSON.stringify({ amount: 1250.00, currency: 'VES' }),
});
const { sessionId } = await res.json();
```

El `sessionId` es de corta vida y acotado a una operación de cobro. Se pasa al SDK en el frontend.

### Tasa de cambio / conversión a VES (opcional)

Si cobras en USD (o quieres mostrar el equivalente en bolívares), al crear la sesión puedes pasar la tasa y el Checkout muestra el monto convertido a VES y la línea "Tasa X Bs/USD":

- `exchangeRate`: bolívares por unidad de la moneda base, como string (ej. `"40.5"` = 40,5 Bs por USD).
- `amounts`: montos explícitos por moneda, ej. `{ "VES": 400 }` (tiene precedencia sobre `exchangeRate`).

```
POST https://api.pagolink.co/v1/checkout/sessions
Body: { "amount": 10.00, "currency": "USD", "exchangeRate": "40.5" }
// El comprador ve el equivalente en Bs y "Tasa 40,5 Bs/USD".
```

La tasa la define tu backend (no hay feed de tasa incorporado); pásala en cada sesión con el valor vigente al momento del cobro.

## 2 · Incluir el SDK (frontend)

```html
<script src="https://cdn.pagolink.co/v1/pagolink.iife.js"></script>
<script>
  const pl = PagoLink('pk_live_…');   // global: window.PagoLink
</script>
```

El global del SDK es `window.PagoLink`.

## 3 · Abrir el cobro

### charge() — modal

Abre el cobro en una ventana modal sobre tu página (Checkout) o el terminal (POS):

```js
pl.charge({
  sessionId,
  onSuccess: (r) => console.log(r.status),   // r = { sessionId, status }
  onCancel:  ()  => console.log('cancelado'),
  onError:   (e) => console.error(e.message),
});
```

### mountCharge() — embebido

Monta el cobro dentro de un contenedor propio (ideal para el POS embebido):

```js
const handle = pl.mountCharge(document.querySelector('#pos-slot'), {
  sessionId,
  onSuccess: (r) => { /* … */ },
});
handle.destroy();   // para desmontar
```

### mountButton() — botón de pago con la marca PagoLink

Renderiza un botón de pago ya diseñado (logo de PagoLink + monocromo, sin dependencias) dentro de un contenedor. Al hacer clic abre el checkout (o el terminal POS con `mode: 'pos'`) con el mismo flujo y callbacks:

```js
const handle = pl.mountButton('#pagar', {   // selector o HTMLElement
  sessionId,
  label: 'Pagar con PagoLink',   // opcional (default: "Pagar con PagoLink")
  mode: 'checkout',              // 'checkout' (default) | 'pos'
  theme: 'dark',                 // 'dark' (default) | 'light'
  onSuccess: (r) => { /* … */ },
  onCancel:  ()  => { /* … */ },
  onError:   (e) => { /* … */ },
});
handle.destroy();   // para remover el botón
```

## Callbacks

| Callback | Payload |
|---|---|
| onSuccess | `{ sessionId, status }` |
| onCancel | — (el usuario cerró el cobro) |
| onError | `{ code, message }` |

El callback del navegador es una señal de UX, no la fuente de verdad. Confirma el estado final en tu backend (webhook o consulta de la sesión).

## Apariencia (appearance)

Personaliza el cobro con `appearance` (o el `branding` de la sesión):

```js
pl.charge({
  sessionId,
  appearance: {
    theme: 'dark',            // 'light' | 'dark' | 'auto'
    colorPrimary: '#F5F5F6',
    colorSuccess: '#00E0C6',
    colorDanger:  '#FF5C5C',
    borderRadius: '12px',
    fontFamily:   'Archivo, sans-serif',
    hideBranding: false,
  },
});
```

## Métodos de pago

| Método | Qué pide |
|---|---|
| Pago Móvil | El cliente paga desde su banco; se verifica el pago entrante. |
| C2P | Banco + teléfono + clave C2P del cliente. |
| Débito Inmediato | OTP de 8 dígitos enviado por SMS al cliente. |
| Transferencia | Datos de cobro; verificación del pago. |
| Binance Pay | QR; el cliente escanea y paga en USDT. |

## Seguridad

- La API key secreta (`sk_…`) vive solo en tu servidor. Nunca en el navegador.
- El frontend solo usa el publishable key (`pk_…`) y el `sessionId` de corta vida.
- El cobro corre en un iframe del origin de PagoLink; el SDK valida el `origin` del comercio en cada mensaje.
- Confirma el estado final del lado del servidor antes de entregar el producto o servicio.