Saltearse al contenido
Nappai Documentation

Stripe Charge

El componente Stripe Charge en la plataforma Nappai es tu puente directo hacia la pasarela de pagos de Stripe. Su propósito principal es facilitarte la gestión de las transacciones monetarias dentro de tus flujos de automatización.

Imagina que este componente actúa como un asistente de caja: puede cobrar a tus clientes, verificar si un pago fue exitoso, recuperar el historial de facturas o actualizar detalles de una compra. Está diseñado para ser intuitivo y robusto, manejando la complejidad de la comunicación con la API de Stripe para que tú puedas concentrarte en la lógica de tu negocio.

¿Cómo funciona?

Internamente, este componente se conecta de forma segura a la infraestructura de Stripe. Cuando activas este nodo en tu flujo de trabajo, Nappai envía una solicitud encriptada a los servidores de Stripe con la información que tú proveas (como el monto a cobrar o el ID del cliente).

Stripe procesa esa solicitud, verifica la disponibilidad de fondos y la seguridad de la tarjeta, y devuelve una respuesta. El componente recibe esta respuesta y la transforma en datos fáciles de leer (como “Éxito” o “Error”) para que puedas tomar decisiones automáticas en tu flujo (por ejemplo, ¿enviar el producto o notificar al cliente?).

Conexión y Credenciales

Este componente requiere configurar previamente una credencial de tipo Stripe API en el panel de Nappai para poder interactuar con el servicio externo:

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo Stripe API y guarda los campos requeridos (principalmente tu API Key, la cual puedes obtener en tu panel de desarrollador de Stripe).
  3. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Nota: Al utilizar esta configuración, asegúrate de estar usando la clave correcta para el entorno de desarrollo o producción que necesites.

Entradas

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

  • Operation: Permite elegir la acción principal que deseas realizar. Puedes elegir entre “Create” (Crear un cargo nuevo), “Get By ID” (Obtener detalles de un cargo específico) o “Get All” (Listar múltiples cargos).
  • Get Mode: Define el comportamiento de recuperación. Úsalo para determinar si quieres recuperar una sola carga por su ID único o si prefieres obtener una lista de cargas.
  • Charge ID: El identificador único de una transacción (usualmente empieza con ch_...). Es obligatorio cuando deseas obtener detalles de una carga específica o actualizarla.
  • Customer ID: El identificador del cliente en Stripe (usualmente empieza con cus_...). Úsalo para asociar el pago a un cliente existente o para filtrar las cargas de un cliente específico.
  • Amount: El monto a cobrar. Importante: Stripe espera el monto en la unidad más pequeña de la moneda (por ejemplo, centavos para dólares USD). Por ejemplo, para cobrar $10.00 USD, debes ingresar 1000.
  • Currency: El código de moneda de tres letras (ISO 4217), como usd para dólares estadounidenses, eur para euros, etc.
  • Source Token: El identificador del método de pago (token). Para pruebas, usa tokens especiales como tok_visa (tarjeta Visa válida), tok_mastercard (Mastercard válida) o tok_chargeDeclined (para simular un pago rechazado). No uses IDs de Payment Methods (pm_) aquí.
  • Description: Un texto breve para describir el cargo (por ejemplo, “Suscripción mensual” o “Compra de producto X”). Esto ayuda a identificar la transacción luego en tu panel de Stripe.
  • Limit: Define cuántas cargas deseas recuperar cuando usas la operación de listado. El valor debe estar entre 1 y 100.

Salidas

Después de ejecutar el componente, recibirás los siguientes datos que puedes usar en el siguiente paso de tu flujo:

  • Charge Data: El objeto completo de la carga devuelto por Stripe. Contiene toda la información detallada, como el estado del pago, fecha, monto exacto y detalles del cliente.
  • List of Charges: Si realizaste una operación de listado, recibirás una lista de objetos, cada uno representando una transacción encontrada.
  • Success Flag: Un indicador simple (Verdadero/Falso) que te dice si la operación se completó sin errores.
  • Error Details: Si algo salió mal (por ejemplo, tarjeta sin fondos o error de red), aquí recibirás el mensaje de error explicando la razón.

Ejemplo de Respuesta JSON

Cuando el componente tiene éxito y crea un cargo o recupera uno existente, verás una estructura de datos similar a esta en la salida Charge Data: json { “id”: “ch_1234567890”, “object”: “charge”, “amount”: 1000, “currency”: “usd”, “captured”: true, “paid”: true, “status”: “succeeded”, “customer”: { “id”: “cus_abc123”, “email”: “cliente@ejemplo.com” }, “created”: 1617123456, “description”: “Pago de suscripción mensual” }

Conectividad

Este componente suele conectarse como parte de un flujo de ventas o facturación:

  • Conectores de Entrada: Comúnmente recibe datos de un nodo de Webhook (cuando llega un pago inicial), de un Trigger de e-commerce, o directamente de un nodo de Formulario donde el usuario introduce los datos de pago.
  • Conectores de Salida: Sus salidas (Charge Data, Success Flag) suelen conectarse a nodos de Decisión (para verificar si el pago fue exitoso) o a nodos de API/HTTP para notificar al cliente (enviar un email de confirmación vía Gmail o Slack) solo si Success Flag es verdadero.

Ejemplo de Uso

Escenario: Quieres automatizar el cobro de una suscripción mensual.

  1. Inicio: Un usuario llena un formulario en tu web con sus datos.
  2. Procesamiento: Usas el componente Stripe Charge configurado así:
    • Operation: Create
    • Amount: 2999 (equivalente a $29.99)
    • Currency: usd
    • Source Token: tok_visa (usando un token de prueba para simular una Visa)
    • Description: “Suscripción Premium Mensual”
  3. Resultado: Si el pago es exitoso, la salida Success Flag será verdadera.
  4. Siguiente Paso: Conectas la salida verdadera a un nodo de Email para enviar el recibo de compra al cliente.

Consejos y Mejores Prácticas

  • Monedas Pequeñas: Recuerda siempre ingresar el monto en centavos (dividido entre 100). Es un error común olvidar esto y cobrar $1000 en lugar de $10.00.
  • Entorno de Prueba: Utiliza siempre tokens de prueba (como tok_visa) mientras desarrollas tu flujo en Nappai para evitar cobros reales accidentales.
  • Seguridad: Nunca compartas tu API Key secreta. Configúrala siempre a través de la sección de Credenciales de Nappai.

Consideraciones de Seguridad

  • Modo Desarrollo: Este componente está optimizado para entornos de desarrollo (is_development = True). Asegúrate de estar utilizando las credenciales de “Test Mode” de Stripe cuando estés probando tus flujos.
  • Validación de Tarjetas: Al usar Source Token, verifica que estés usando el formato correcto (tok_...). El uso de IDs de métodos de pago (pm_...) en este campo específico puede resultar en errores de validación, ya que este componente usa la API de Cargos clásica.