Documentación de integración

Todos los métodos. Una integración.

PagoLink es la infraestructura de pagos de Venezuela. Con una sola integración aceptás 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 (integrá pagos en tu 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.

⌁

El global JavaScript del SDK se expone como window.PagoLink.

Para IA · agentes

Toda la doc en un llms.txt

La referencia de integración completa en Markdown plano, lista para el contexto de tu asistente.

→

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`

Todas las llamadas de servidor usan la API con prefijos /v1, /accounts/v1 y /billing/v1.

1 · Crear una sesión

Desde tu backend, con tu API key secreta, crea una sesión de cobro. Nunca expongas la API key en el navegador.

// POST https://api.pagolink.co/v1/checkout/sessions  (Checkout y Terminal POS)
// x-api-key: sk_live_…
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();

Devuelve un sessionId de corta vida, acotado a una operación de cobro. Ese id se pasa al SDK en el frontend.

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

Si cobras en USD y quieres mostrar el equivalente en bolívares, pasa la tasa al crear la sesión. 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).

// cobrar 10 USD mostrando el equivalente en Bs
  body: JSON.stringify({ amount: 10.00, currency: 'USD', exchangeRate: '40.5' }),

La tasa la define tu backend con el valor vigente al momento del cobro (no hay feed de tasa incorporado).

Incluir el SDK

<!-- CDN -->
<script src="https://cdn.pagolink.co/v1/pagolink.iife.js"></script>

<script>
  const pl = PagoLink('pk_live_…');  // tu publishable key
</script>

El publishable key (pk_…) es seguro para el frontend. La API key secreta (sk_…) va solo en el servidor.

Modal charge()

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

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

Embebido mountCharge()

Monta el cobro dentro de un contenedor de tu propia UI (ideal para el POS embebido).

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

// para desmontar
handle.destroy();

Botón mountButton()

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

const handle = pl.mountButton('#pagar', {   // selector o HTMLElement
  sessionId,
  label: 'Pagar con PagoLink',   // opcional (default)
  mode:  'checkout',              // 'checkout' (default) | 'pos'
  theme: 'dark',                 // 'dark' (default) | 'light'
  onSuccess: (r) => { /* … */ },
});

// para remover el botón
handle.destroy();

Callbacks

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

⌁

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

Apariencia

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

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.