Package Exports

recurrente-checkout
recurrente-checkout/recurrente-checkout.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (recurrente-checkout) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Checkout Recurrente - Guía de Integración

npm version

Recurrente Checkout es una librería JavaScript que te permite insertar un checkout responsivo y seguro en tu propia página web. Funciona mostrando un iframe con tu sesión de pago y maneja callbacks para eventos clave como éxito, fallo o pagos en proceso.

Instalación

NPM (Recomendado)

npm install recurrente-checkout

CDN

⚠️ En producción, recomendamos usar una versión específica (por ejemplo, @0.0.4) en lugar de @latest, para evitar romper integraciones al actualizar automáticamente.

Unpkg

<script src="https://unpkg.com/recurrente-checkout@latest/recurrente-checkout.js"></script>

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/recurrente-checkout@latest/recurrente-checkout.js"></script>

Uso

Antes de comenzar: Para usar esta biblioteca, necesitas crear un checkout en Recurrente. Consulta la documentación de creación de checkouts para obtener tu URL de checkout.

¿Dónde aparece el checkout?

El checkout de Recurrente se renderiza como un iframe que se inserta automáticamente en el elemento HTML con el ID recurrente-checkout-container. Asegúrate de tener este elemento en tu página:

<div id="recurrente-checkout-container"></div>

El iframe se ajustará automáticamente al tamaño del contenedor y será responsive. Puedes personalizar la apariencia aplicando estilos CSS al contenedor.

ES6 Modules (Recomendado)

import RecurrenteCheckout from 'recurrente-checkout';

RecurrenteCheckout.load({
  url: "https://app.recurrente.com/checkout-session/ch_1234",
  onSuccess: function(paymentData) {
    console.log('Pago exitoso:', paymentData);
    // Manejar pago exitoso
    // ej., redirigir a página de éxito, actualizar UI, etc.
  },
  onFailure: function(error) {
    console.log('Pago fallido:', error);
    // Manejar pago fallido
    // ej., mostrar mensaje de error, opción de reintentar, etc.
  },
  onPaymentInProgress: function() {
    console.log('Pago con transferencia bancaria en proceso');
    // Este callback se ejecuta solo para transferencias bancarias
    // El pago puede tomar hasta 24 horas en procesarse
    // ej., mostrar mensaje informativo, enviar email de confirmación, etc.
  }
});

Importación Nominal

import { loadRecurrenteCheckout } from 'recurrente-checkout';

loadRecurrenteCheckout({
  url: "https://app.recurrente.com/checkout-session/ch_1234",
  onSuccess: function(paymentData) {
    console.log('Pago exitoso:', paymentData);
  },
  onFailure: function(error) {
    console.log('Pago fallido:', error);
  },
  onPaymentInProgress: function() {
    console.log('Pago con transferencia bancaria en proceso');
    // Solo para transferencias bancarias (puede tomar hasta 24h)
  }
});

CommonJS

const RecurrenteCheckout = require('recurrente-checkout');

RecurrenteCheckout.load({
  url: "https://app.recurrente.com/checkout-session/ch_1234",
  onSuccess: function(paymentData) {
    console.log('Pago exitoso:', paymentData);
  },
  onFailure: function(error) {
    console.log('Pago fallido:', error);
  },
  onPaymentInProgress: function() {
    console.log('Pago con transferencia bancaria en proceso');
    // Solo para transferencias bancarias (puede tomar hasta 24h)
  }
});

Navegador (Global)

<script src="https://unpkg.com/recurrente-checkout@latest/recurrente-checkout.js"></script>
<script>
  RecurrenteCheckout.load({
    url: "https://app.recurrente.com/s/your-checkout-url",
    onSuccess: function(paymentData) {
      console.log('Pago exitoso:', paymentData);
    },
    onFailure: function(error) {
      console.log('Pago fallido:', error);
    },
    onPaymentInProgress: function() {
      console.log('Pago con transferencia bancaria en proceso');
      // Solo para transferencias bancarias (puede tomar hasta 24h)
    }
  });
</script>

Integración Rápida

1. Incluir la Biblioteca JavaScript

Elige uno de los métodos de instalación anteriores.

2. Inicializar el Checkout

Elige uno de los dos métodos de integración:

Método A: URL de Checkout Directa

RecurrenteCheckout.load({
  url: "https://app.recurrente.com/checkout-session/ch_1234",
  onSuccess: function(paymentData) {
    console.log('Pago exitoso:', paymentData.checkoutId);
    // Manejar pago exitoso
    // ej., redirigir a página de éxito, actualizar UI, etc.
  },
  onFailure: function(data) {
    console.log('Pago fallido:', data.error);
    // Manejar pago fallido
    // ej., mostrar mensaje de error, opción de reintentar, etc.
  },
  onPaymentInProgress: function() {
    console.log('Pago con transferencia bancaria en proceso');
    // Este callback se ejecuta solo para transferencias bancarias
    // El pago puede tomar hasta 24 horas en procesarse
    // ej., mostrar mensaje informativo, enviar email de confirmación, etc.
  }
});

Método B: URL de Producto

También puedes usar una URL de producto con el formato https://app.recurrente.com/s/{organization}/{product-slug}:

RecurrenteCheckout.load({
  url: "https://app.recurrente.com/s/mi-cuenta/mi-producto",
  onSuccess: function(paymentData) {
    console.log('Pago exitoso:', paymentData);
    // Manejar pago exitoso
    // ej., redirigir a página de éxito, actualizar UI, etc.
  },
  onFailure: function(error) {
    console.log('Pago fallido:', error);
    // Manejar pago fallido
    // ej., mostrar mensaje de error, opción de reintentar, etc.
  },
  onPaymentInProgress: function() {
    console.log('Pago con transferencia bancaria en proceso');
    // Este callback se ejecuta solo para transferencias bancarias
    // El pago puede tomar hasta 24 horas en procesarse
    // ej., mostrar mensaje informativo, enviar email de confirmación, etc.
  }
});

Nota: Reemplaza mi-cuenta con tu slug de organización y mi-producto con tu slug de producto.

Callbacks y Manejo de Respuestas

Callback `onSuccess`

El callback onSuccess se ejecuta cuando el pago se completa exitosamente:

onSuccess: function(paymentData) {
  console.log('Pago exitoso:', paymentData);

  // Manejar pago exitoso
  // ej., redirigir a página de éxito, actualizar UI, etc.
}

Callback `onFailure`

El callback onFailure se ejecuta cuando el pago falla:

onFailure: function(message) {
  console.log('Pago fallido:', message);

  // Opcional: Manejar mensajes de notificación específicos
  if (message.notice) {
    console.log('Mensaje de notificación:', message.notice);
    // Mostrar mensaje personalizado al usuario
    // Por ejemplo: "Tarjeta rechazada", "Fondos insuficientes", etc.
  }

  // Manejar pago fallido
  // if (message.error) {
    // ej., mostrar mensaje de error, redireccionar a pagina de error, etc.
  }
}

Callback `onPaymentInProgress`

El callback onPaymentInProgress se ejecuta solo para transferencias bancarias en proceso:

onPaymentInProgress: function(paymentData) {
  console.log('Pago con transferencia bancaria en proceso:', paymentData);
  // ej., mostrar mensaje informativo, enviar email de confirmación, etc.
}

Solución de Problemas

Problemas Comunes

Iframe no carga: Verifica que la URL de checkout sea accesible
Errores CORS: Asegúrate de que tu backend permita solicitudes desde tu dominio frontend
Errores de API: Verifica tus claves de API de Recurrente y permisos
Contenido mixto: Usa HTTPS tanto para frontend como backend en producción

Modo Debug

La biblioteca incluye logging en consola. Revisa la consola del navegador para información detallada sobre el proceso de checkout.

Ejemplo Completo

Consulta el directorio examples/ para ejemplos de implementaciones completas.

Ejemplos Disponibles

🌐 PHP (`examples/php/`)

Framework: PHP vanilla con servidor integrado
Puerto: 8000
Ejecutar: php -S localhost:8000
Estructura: Servidor web simple con soporte CORS, páginas de éxito/fallo

⚛️ React (`examples/react/`)

Framework: React 18 con React Router
Puerto: 3000
Ejecutar: npm install && npm start
Estructura: Arquitectura basada en componentes, enrutamiento del lado del cliente

🔷 C# (`examples/csharp/`)

Framework: ASP.NET Core 7.0 MVC
Puerto: 7001 (HTTPS) / 5001 (HTTP)
Ejecutar: dotnet run
Estructura: Patrón MVC, vistas Razor, servicio de archivos estáticos

☕ Java (`examples/java/`)

Framework: Spring Boot 3.1 con Thymeleaf
Puerto: 8080
Ejecutar: mvn spring-boot:run
Estructura: Spring MVC, motor de plantillas Thymeleaf, auto-configuración

🏛️ ASP Classic (`examples/asp/`)

Framework: ASP Classic (VBScript) con IIS
Puerto: 80 (IIS por defecto)
Ejecutar: Configurar directorio virtual de IIS
Estructura: Procesamiento del lado del servidor, manejo de parámetros de consulta

Inicio Rápido con Ejemplos

Navega al directorio de tu tecnología preferida: cd examples/[tecnología]
Sigue las instrucciones específicas del README de cada ejemplo
Accede a la aplicación en el puerto correspondiente

Consideraciones para Producción

Usa HTTPS en producción
Configura webhooks para transferencias bancarias

Soporte

Para crear checkouts: Consulta la documentación de creación de checkouts
Para preguntas de integración: Revisa esta guía y las implementaciones de ejemplo
Si te quedan más dudas o tienes problemas, únete a nuestro Discord

recurrente-checkout