venepagos

v1.0.2

Published

9 months ago

SDK oficial de VenePagos para integrar pagos en aplicaciones web

0High
0Medium
0Low

venepagos

venepagos payments venezuela sdk pasarela pagos

SDK de VenePagos

SDK oficial de VenePagos para integrar pagos en bolivares automatizado en aplicaciones web

🚀 Características

✅ Fácil integración: Implementa pagos en minutos
🔒 Seguro: Todas las transacciones son procesadas de forma segura
💰 Múltiples monedas: Soporte para USD y VES
🖼️ Ventanas emergentes: Experiencia de usuario fluida con popups
📱 Responsive: Funciona en desktop y móvil
🎯 TypeScript: Soporte completo con tipado
🔄 Eventos en tiempo real: Detecta el estado del pago automáticamente

📦 Instalación

npm install venepagos

O usando yarn:

yarn add venepagos

Para uso directo en el navegador:

<script src="https://unpkg.com/@venepagos/payment-sdk@latest/index.js"></script>

🔧 Configuración inicial

1. Obtener API Key

Primero necesitas obtener tu API Key desde el panel de VenePagos:

Inicia sesión en VenePagos
Ve a Perfil → API Keys
Crea una nueva API Key
Copia la clave (debe comenzar con vp_)

2. Inicializar el SDK

import VenePagosSDK from '@venepagos/payment-sdk';

// Inicializar el SDK
const venepagos = new VenePagosSDK({
  apiKey: 'vp_tu_api_key_aqui',
  baseUrl: 'https://www.venepagos.com.ve', // Opcional
  sandbox: false // Opcional: true para pruebas
});

Para JavaScript sin ES modules:

const VenePagosSDK = require('@venepagos/payment-sdk');

const venepagos = new VenePagosSDK({
  apiKey: 'vp_tu_api_key_aqui'
});

En el navegador:

<script>
const venepagos = new VenePagosSDK({
  apiKey: 'vp_tu_api_key_aqui'
});
</script>

🎯 Ejemplos de uso

Ejemplo básico - Crear y abrir pago

async function procesarPago() {
  try {
    const resultado = await venepagos.createAndOpenPayment({
      title: 'Compra de productos',
      description: 'Pago por productos del carrito',
      amount: 25.99,
      currency: 'USD',
      expiresAt: VenePagosSDK.utils.generateExpiryDate(24) // Expira en 24 horas
    });

    console.log('¡Pago exitoso!', resultado.paymentResult.reference);
  } catch (error) {
    console.error('Error en el pago:', error.message);
  }
}

Ejemplo avanzado - Con eventos

// Configurar listeners de eventos
venepagos.on('success', (data) => {
  console.log('Pago exitoso:', data.reference);
  // Actualizar la interfaz, redirigir, etc.
});

venepagos.on('error', (data) => {
  console.error('Error en el pago:', data.error);
  // Mostrar mensaje de error al usuario
});

venepagos.on('cancel', (data) => {
  console.log('Pago cancelado por el usuario');
});

// Crear payment link
const paymentLink = await venepagos.createPaymentLink({
  title: 'Suscripción Premium',
  amount: 9.99,
  currency: 'USD'
});

// Abrir ventana de pago con opciones personalizadas
const resultado = await venepagos.openPaymentPopup(paymentLink.url, {
  width: 800,
  height: 600,
  centered: true
});

Ejemplo React

import React, { useState } from 'react';
import VenePagosSDK from '@venepagos/payment-sdk';

const venepagos = new VenePagosSDK({
  apiKey: process.env.REACT_APP_VENEPAGOS_API_KEY
});

function PagoComponent() {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState(null);

  const handlePago = async () => {
    setLoading(true);
    try {
      const resultado = await venepagos.createAndOpenPayment({
        title: 'Producto Premium',
        amount: 49.99,
        currency: 'USD'
      });
  
      setResult(resultado.paymentResult);
    } catch (error) {
      console.error('Error:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={handlePago} disabled={loading}>
        {loading ? 'Procesando...' : 'Pagar $49.99'}
      </button>
  
      {result && result.success && (
        <div className="success">
          ¡Pago exitoso! Referencia: {result.reference}
        </div>
      )}
    </div>
  );
}

Ejemplo con monto variable

// Para pagos donde el usuario define el monto
const paymentLink = await venepagos.createPaymentLink({
  title: 'Donación',
  description: 'Apoya nuestro proyecto',
  // No especificar amount para monto variable
  currency: 'USD'
});

console.log('URL de pago:', paymentLink.url);

📚 Referencia de API

Constructor

new VenePagosSDK(config: VenePagosConfig)

Parámetros:

config.apiKey (string): Tu API Key de VenePagos
config.baseUrl (string, opcional): URL base de la API
config.sandbox (boolean, opcional): Modo de pruebas

Métodos principales

`createPaymentLink(paymentData)`

Crea un nuevo enlace de pago.

createPaymentLink(paymentData: PaymentLinkData): Promise<PaymentLink>

Parámetros:

interface PaymentLinkData {
  title: string;              // Título del pago (mín. 3 caracteres)
  description?: string;       // Descripción opcional
  amount?: number;           // Monto (opcional para monto variable)
  currency?: 'USD' | 'VES';  // Moneda
  expiresAt?: string;        // Fecha de expiración (ISO 8601)
}

Retorna:

interface PaymentLink {
  id: string;
  title: string;
  description?: string;
  amount?: number;
  currency: string;
  url: string;
  isActive: boolean;
  expiresAt?: string;
  createdAt: string;
}

`openPaymentPopup(paymentUrl, options)`

Abre una ventana emergente con el enlace de pago.

openPaymentPopup(paymentUrl: string, options?: PopupOptions): Promise<PaymentResult>

Opciones:

interface PopupOptions {
  width?: number;    // Ancho (por defecto: 600)
  height?: number;   // Alto (por defecto: 700)
  centered?: boolean; // Centrar (por defecto: true)
}

`createAndOpenPayment(paymentData, popupOptions)`

Crea un payment link y abre inmediatamente la ventana de pago.

createAndOpenPayment(
  paymentData: PaymentLinkData, 
  popupOptions?: PopupOptions
): Promise<PaymentProcess>

`listPaymentLinks(options)`

Lista todos tus payment links.

listPaymentLinks(options?: ListOptions): Promise<PaymentLinkList>

Opciones:

interface ListOptions {
  limit?: number;     // Máximo 100
  offset?: number;    // Para paginación
  isActive?: boolean; // Filtrar por estado
}

`getPaymentLink(paymentLinkId)`

Obtiene información de un payment link específico.

getPaymentLink(paymentLinkId: string): Promise<PaymentLink>

Eventos

`on(event, callback)`

Configura un listener para eventos de pago.

venepagos.on('success', (data) => {
  console.log('Pago exitoso:', data.reference);
});

venepagos.on('error', (data) => {
  console.error('Error:', data.error);
});

venepagos.on('cancel', (data) => {
  console.log('Pago cancelado');
});

`off(event, callback)`

Remueve un listener de eventos.

Utilidades

`VenePagosSDK.utils.formatAmount(amount, currency)`

Formatea un monto para mostrar.

const formatted = VenePagosSDK.utils.formatAmount(25.99, 'USD');
console.log(formatted); // "$25.99"

`VenePagosSDK.utils.generateExpiryDate(hours)`

Genera una fecha de expiración.

const expiry = VenePagosSDK.utils.generateExpiryDate(48); // 48 horas

`VenePagosSDK.utils.isValidExpiryDate(expiresAt)`

Valida si una fecha de expiración es válida.

const isValid = VenePagosSDK.utils.isValidExpiryDate('2024-12-31T23:59:59Z');

🔐 Seguridad

Nunca expongas tu API Key en el código cliente en producción
Usa variables de entorno para almacenar credenciales
Para aplicaciones del lado del cliente, considera usar un backend proxy
Las API Keys deben comenzar con vp_

Ejemplo seguro para React

// .env.local
REACT_APP_VENEPAGOS_API_KEY=vp_tu_api_key

// Componente
const venepagos = new VenePagosSDK({
  apiKey: process.env.REACT_APP_VENEPAGOS_API_KEY
});

🎨 Personalización de UI

Estilos de la ventana emergente

La ventana de pago es responsiva y se adapta automáticamente. Puedes controlar las dimensiones:

const resultado = await venepagos.openPaymentPopup(url, {
  width: 800,    // Más ancho para desktop
  height: 900,   // Más alto
  centered: true // Centrado en pantalla
});

Detección de cierre de ventana

try {
  const resultado = await venepagos.openPaymentPopup(url);
  // Pago completado exitosamente
} catch (error) {
  if (error.message.includes('cerrada por el usuario')) {
    console.log('El usuario cerró la ventana');
  }
}

🔍 Debugging y manejo de errores

Validación de API Key

const isValid = await venepagos.validateApiKey();
if (!isValid) {
  console.error('API Key inválida');
}

Errores comunes

| Error | Causa | Solución | | ----------------------------------- | ---------------------------- | -------------------------------------------------- | | API Key es requerido | No se proporcionó API Key | Agregar API Key en la configuración | | API Key debe comenzar con "vp_" | Formato incorrecto | Verificar que la API Key tenga el formato correcto | | Error HTTP 401 | API Key inválida o expirada | Generar nueva API Key | | Error HTTP 400 | Datos inválidos | Verificar los datos del payment link | | Ventana emergente bloqueada | Bloqueador de popups activo | Instruir al usuario para permitir popups |

Logging detallado

// Habilitar logging en desarrollo
venepagos.on('success', console.log);
venepagos.on('error', console.error);
venepagos.on('cancel', console.warn);

🌐 Compatibilidad

Navegadores: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
Node.js: 14.0+
React: 16.8+
Vue: 2.6+ / 3.0+
Angular: 9+

📱 Responsive

El SDK y las páginas de pago son completamente responsivas:

Desktop: Ventana emergente optimizada
Mobile: Redirección a página de pago adaptada
Tablet: Experiencia híbrida optimizada

🚀 Mejores prácticas

1. Manejo de estados

class PaymentManager {
  constructor() {
    this.venepagos = new VenePagosSDK({ apiKey: 'tu_api_key' });
    this.setupEventListeners();
  }

  setupEventListeners() {
    this.venepagos.on('success', this.onPaymentSuccess.bind(this));
    this.venepagos.on('error', this.onPaymentError.bind(this));
  }

  async processPayment(amount) {
    try {
      return await this.venepagos.createAndOpenPayment({
        title: 'Compra',
        amount,
        currency: 'USD'
      });
    } catch (error) {
      this.handleError(error);
    }
  }

  cleanup() {
    this.venepagos.destroy();
  }
}

2. Caché de payment links

const cache = new Map();

async function getOrCreatePaymentLink(productId, amount) {
  if (cache.has(productId)) {
    return cache.get(productId);
  }

  const paymentLink = await venepagos.createPaymentLink({
    title: `Producto ${productId}`,
    amount,
    currency: 'USD'
  });

  cache.set(productId, paymentLink);
  return paymentLink;
}

3. Reintentos automáticos

async function createPaymentWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await venepagos.createPaymentLink(data);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * i));
    }
  }
}

🔄 Migración

Desde otras pasarelas

Si estás migrando desde otra pasarela de pagos:

// Antes (genérico)
function openPayment(amount) {
  window.open(`https://otras-pasarela.com/pay?amount=${amount}`);
}

// Después (VenePagos)
async function openPayment(amount) {
  try {
    const resultado = await venepagos.createAndOpenPayment({
      title: 'Pago',
      amount,
      currency: 'USD'
    });
    console.log('Pago exitoso:', resultado.paymentResult.reference);
  } catch (error) {
    console.error('Error:', error);
  }
}

🤝 Soporte

Documentación: https://docs.venepagos.com.ve
Issues: GitHub Issues
Email: [email protected]