Saltearse al contenido
Nappai Documentation

Stripe Payment Intent

Este componente, llamado Stripe Payment Intent, es una herramienta esencial dentro del sistema de automatización Nappai para gestionar pagos digitales de forma segura y eficiente. Funciona como un puente inteligente entre tu automatización y Stripe, el líder mundial en procesamiento de pagos online.

Su propósito principal es ayudarte a controlar todo el proceso de una transacción: desde el momento en que creas una intención de cobro, pasando por la autenticación del cliente (como la verificación bancaria), hasta la confirmación final del pago y la captura del dinero. Es ideal para e-commerce, suscripciones o servicios donde necesitas asegurar que los fondos estén disponibles antes de entregar un producto.

¿Cómo funciona?

Imagina que Stripe Payment Intent actúa como el “cajero inteligente” de tu tienda. No solo cobra la tarjeta, sino que gestiona la seguridad y el estado del pago paso a paso.

  1. Creación: Inicias un proceso de pago indicando el monto y la moneda. El sistema genera un código único para esa transacción.
  2. Autenticación (3D Secure): Si es necesario, el componente prepara la interacción para que el cliente verifique su identidad con su banco (por ejemplo, con una app móvil o un SMS), cumpliendo con las normativas de seguridad más estrictas.
  3. Confirmación: Una vez que el cliente ha pagado, puedes decidir si el pago se confirma automáticamente o si requiere una revisión manual.
  4. Captura: Finalmente, el dinero se reserva o se transfiere realmente a tu cuenta. Puedes hacerlo de inmediato (automático) o esperar a que envíes el producto (manual).

El componente utiliza credenciales seguras para hablar directamente con la API de Stripe, asegurando que cada paso sea válido y registrado correctamente.

Conexión y Credenciales

Para que este componente funcione, es fundamental que conectes tu cuenta de Nappai con tu cuenta de Stripe de forma segura. Esto se logra mediante una credencial API.

Sigue estos pasos para configurarla:

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo Stripe API.
  3. Ingresa tu API Key secreta (puedes encontrarla en tu panel de desarrollador de Stripe). Guarda la configuración.
  4. Vuelve a tu flujo de trabajo y, en el campo Credential de este nodo, selecciona la credencial que acabas de crear.

Nota importante: No necesitas ingresar claves técnicas manualmente en cada nodo. Solo una vez en la sección de Credenciales del sistema, y luego seleccionas la conexión aquí.

Operaciones

Este componente permite realizar múltiples acciones sobre un pago dependiendo de lo que necesites hacer en tu flujo de automatización. Puedes elegir una operación específica en el campo Operation.

  • Create: Crea una nueva intención de pago para cobrar a un cliente. Es el primer paso para iniciar una transacción.
  • Retrieve: Consulta el estado actual de un pago existente usando su ID. Útil para verificar si un pago fue exitoso o si está pendiente.
  • Update: Modifica los detalles de una intención de pago ya creada (por ejemplo, agregar información de envío o actualizar un monto).
  • Confirm: Confirma el método de pago. Le dice a Stripe que está listo para procesar el cobro. Es esencial para transacciones que requieren autenticación del usuario.
  • Capture: Toma el dinero de la tarjeta del cliente. Se usa si configuraste el pago como “manual” o si necesitas retener los fondos hasta el envío.
  • Cancel: Cancela una intención de pago. Libera cualquier retención en la tarjeta del cliente y evita el cobro.
  • List: Obtiene una lista de múltiples intenciones de pago según criterios específicos.

Entradas

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Asegúrate de completarlos según la operación que hayas seleccionado.

  • Operation: Selecciona la acción principal que deseas realizar (Crear, Consultar, Actualizar, etc.).
  • Mode: Define cómo buscas los datos.
    • Visible en: List
  • Payment Intent ID: El identificador único del pago (comienza con pi_...). Es obligatorio para operaciones como Consultar, Actualizar, Confirmar, Capturar y Cancelar.
    • Visible en: Retrieve, Update, Confirm, Capture, Cancel
  • Customer ID: El ID del cliente de Stripe (comienza con cus_...). Es opcional pero recomendado para guardar métodos de pago y futuros usos.
    • Visible en: Create, List
  • Amount: El monto a cobrar. Importante: Ingresa el monto en la unidad más pequeña de la moneda (por ejemplo, centavos). Si quieres cobrar $10.00 USD, escribe 1000.
    • Visible en: Create
  • Currency: El código de moneda de tres letras (ej. usd, eur, mxn).
    • Visible en: Create
  • Description: Una nota o descripción breve sobre el pago (ej. “Suscripción Mensual”).
    • Visible en: Create
  • Payment Method ID: El ID específico del método de pago (ej. tarjeta de crédito). Incluye IDs de prueba como pm_card_visa para pruebas.
    • Visible en: Confirm
  • Confirm Immediately: Indica si el pago debe confirmarse automáticamente al crearlo o si debe esperar una acción externa.
    • Visible en: Create
  • Capture Method: Define si el cobro es inmediato (automatic) o si se retiene para cobrarlo después (manual).
    • Visible en: Create
  • Allow Redirects: Controla si el cliente debe ser redirigido a su banco para autenticarse (never o always).
    • Visible en: Create
  • Return URL: La dirección web a la que el cliente volverá después de completar la autenticación 3D Secure.
    • Visible en: Create
  • Setup Future Usage: Indica si deseas guardar este método de pago para cobros futuros (suscripciones).
    • Visible en: Create
  • Limit: El número máximo de registros a devolver en una lista.
    • Visible en: List

Salidas

Al ejecutar este componente, recibirás información detallada sobre el estado del pago, lo cual es crucial para decidir los siguientes pasos en tu automatización.

Ejemplo de Respuesta JSON

Cuando una operación se ejecuta correctamente (por ejemplo, al crear un pago), recibirás datos estructurados como este: json { “success”: true, “intent_id”: “pi_3OwJ5d2eZaKy1234”, “status”: “requires_payment_method”, “client_secret”: “pi_3OwJ5d2eZaKy1234_secret_ABC…”, “amount”: 1000, “currency”: “usd”, “payment_method”: “pm_card_visa” }

  • success: Indica si la operación funcionó (true) o falló (false).
  • intent_id: El ID único del pago (pi_...). Guárdalo para usarlo en pasos posteriores (como confirmar o cancelar).
  • status: El estado actual del pago. Puede ser requires_payment_method (pendiente de pago), succeeded (exitoso), canceled (cancelado), etc.
  • client_secret: Una clave temporal necesaria si necesitas completar la autenticación desde una página web o aplicación del cliente (Stripe.js).
  • amount y currency: El monto y moneda procesados.

Conectividad

Este componente actúa como un nodo central en el flujo de pagos. Lógicamente, se conecta de la siguiente manera:

  • Conexión de Salida (After Create): La salida de una operación Create suele conectarse directamente a un componente que notifica al cliente (por ejemplo, un correo electrónico con el enlace de pago) o a un componente de Confirm si deseas automatizar todo el proceso sin interacción manual inmediata.
  • Conexión de Entrada (Before Update/Capture): Las salidas de Retrieve o Create (específicamente el intent_id) son entradas vitales para Update (si necesitas cambiar detalles) o Capture (si necesitas cobrar el dinero retenido).
  • Integración con Bases de Datos: El intent_id y el status pueden mapearse a una base de datos (como SQL o MongoDB) para registrar la transacción y sincronizar el inventario o el estado del pedido.

Ejemplo de Uso

Escenario: Automatización de una Venta Online

  1. Crear Pago: Usas el componente con la operación Create. Defines el monto ($50.00 -> 5000), la moneda (usd) y seleccionas “Automatic” para el cobro.
  2. Verificar Estado: El componente devuelve un status de succeeded.
  3. Procesar Pedido: En tu flujo, usas la salida success: true para activar un nodo de envío de email de confirmación.
  4. Gestión de Errores: Si el status es requires_action (el cliente necesita verificar su banco), puedes redirigir el flujo a un nodo que muestre el formulario de pago en tu sitio web.

Consejos y Mejores Prácticas

  • Usa montos en centavos: Recuerda que Stripe no acepta decimales directos en el campo Amount. Usa 1000 para $10.00 para evitar errores de formato.
  • Maneja el “3D Secure”: Si estás en una región con regulaciones estrictas (como Europa), asegúrate de que el flujo de tu sitio web esté preparado para manejar redirecciones de banco cuando el status indique requires_action.
  • Seguridad con Client Secret: El campo client_secret es sensible. No lo expongas en tu código frontend público si puedes evitarlo; úsalo internamente para iniciar el pago de forma segura.
  • Prueba con IDs de Tarjeta: Usa IDs de prueba como pm_card_visa para simular pagos exitosos o pm_card_chargeDeclined para verificar cómo tu automatización maneja las fallas, sin gastar dinero real.

Consideraciones de Seguridad

  • API Keys Secretas: Asegúrate de que la API Key que configures en la sección de Credenciales tenga los permisos mínimos necesarios (solo lectura para “Retrieve” y “List”, y write para “Create” y “Confirm”).
  • Manejo de Errores: Configura tu flujo para capturar errores. Si el componente devuelve success: false, el campo error_message te dará pistas sobre por qué falló (fondos insuficientes, tarjeta rechazada, etc.).