Stripe Refund

Guía de Usuario: Componente Stripe Refund

Bienvenido a la documentación del componente Stripe Refund dentro del sistema de automatización Nappai.

Este componente es tu herramienta principal para gestionar las devoluciones de dinero (reembolsos) cuando utilizas Stripe como tu pasarela de pagos. Te permite crear reembolsos, consultar el estado de los mismos y actualizar información si es necesario, todo integrado en tus flujos de trabajo de automatización.

Imagina que tienes una venta en tu tienda online. Si un cliente solicita devolver un producto, este componente es el que se encarga de ejecutar la devolución del dinero en la cuenta bancaria del cliente y registrar la operación en tus sistemas.

¿Cómo funciona?

El componente Stripe Refund actúa como un puente seguro entre tu automatización en Nappai y la API de Stripe.

Internamente, el componente sigue estos pasos:

Verificación: Comprobamos que tienes una conexión válida con tu cuenta de Stripe (a través de las credenciales que configures).
Acción: Dependiendo de lo que necesites, el componente ejecuta una acción específica (como devolver dinero o consultar un estado).
Resultado: Stripe procesa la solicitud y devuelve la confirmación. El componente captura esta respuesta y la pone a tu disposición para que puedas usarla en los siguientes pasos de tu flujo (por ejemplo, para enviar un correo de confirmación o actualizar tu base de datos de clientes).

Nota técnica: Este componente está optimizado para funcionar en modo “Mapeo”, lo que significa que está diseñado para fluir naturalmente dentro de cadenas de automatización complejas, enviando y recibiendo datos de forma estructurada.

Conexión y Credenciales

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

Dirígete a la sección de Credenciales en tu panel de Nappai.
Crea una nueva credencial del tipo Stripe API y guarda los campos requeridos (claves de API, tokens, etc.).
En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Entradas

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

Fixed (Fijo): Escribes el valor directamente en el campo.
Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Estos campos te permiten definir cómo y qué reembolsos gestionar:

Mode: Define si quieres interactuar con un único reembolso específico o listar todos los reembolsos disponibles.
- Visible en: Todas las operaciones
Refund ID: El identificador único del reembolso (generalmente comienza con re_). Es necesario si deseas obtener información detallada sobre un reembolso que ya fue creado.
- Visible en: Todas las operaciones
Charge ID: El identificador del pago original que deseas reembolsar (generalmente comienza con ch_). Este campo es esencial cuando vas a crear un nuevo reembolso.
- Visible en: Todas las operaciones
Amount: La cantidad a reembolsar. Se debe expresar en la unidad más pequeña de la moneda (por ejemplo, centavos para USD). Si lo dejas vacío, el sistema reembolsará el monto total del pago original.
- Visible en: Todas las operaciones
Reason: La razón del reembolso. Es un dato importante para auditorías y estadísticas. Las opciones comunes incluyen duplicado, fraude o solicitado por el cliente.
- Visible en: Todas las operaciones
Description: Una descripción corta que se guarda en los metadatos del reembolso. Útil para añadir notas internas sobre por qué se está realizando esa devolución.
- Visible en: Todas las operaciones
Limit: Un número entero que limita cuántos registros se devolverán cuando se usen listas, útil para manejar grandes volúmenes de datos de forma eficiente.
- Visible en: Todas las operaciones

Salidas

Al ejecutarse correctamente, este componente producirá los siguientes resultados que podrás usar en nodos posteriores de tu automatización:

refund_object: Un objeto completo que contiene todos los detalles del reembolso. Incluye información como el ID del reembolso, el monto, la moneda, el estado actual (pendiente, completado, etc.) y la fecha de creación. Este es el dato principal para verificar que el reembolso se realizó correctamente.
success: Un indicador booleano (True o False) que te confirma si la operación se ejecutó sin errores.

Ejemplo de Respuesta JSON

A continuación, puedes ver un ejemplo de cómo se ve la respuesta típica del componente cuando se recupera o crea un reembolso exitosamente. Este formato te ayuda a saber qué datos puedes “mapear” o conectar en los siguientes pasos de tu flujo. json { “id”: “re_1234567890”, “object”: “refund”, “amount”: 1500, “currency”: “usd”, “metadata”: {}, “payment”: “ch_0987654321”, “reason”: “requested_by_customer”, “status”: “succeeded”, “created”: 1678886400 }

Conectividad

Este componente es una pieza clave en flujos de gestión de ventas y post-venta. Lógicamente, se conecta de la siguiente manera:

Entrada: Recibe datos del componente que procesa los pagos originales (como Stripe Payment o Stripe Charge) para saber qué pago debe reembolsar. También recibe los datos de la credencial de Stripe API para establecer la conexión segura.
Salida: Sus salidas (especialmente refund_object y success) suelen conectarse a componentes de notificación (como Send Email o Slack) para informar al cliente o al equipo de soporte de que el reembolso se ha procesado, o a componentes de base de datos para actualizar el historial de transacciones.

Ejemplo de Uso

Escenario: Un cliente compra un producto por $50 USD y luego solicita la devolución porque le llegó el artículo equivocado. Quieres automatizar la devolución del dinero y notificar al cliente.

Configura el flujo:
- Añade el componente Stripe Refund.
- En el campo Mode, selecciona cómo deseas operar (por ejemplo, “By ID” si ya tienes el ID del reembolso anterior, o simplemente configuras el Charge ID del pago original si estás creando el reembolso desde cero).
- En el campo Charge ID, mapea el ID del pago original obtenido del componente de ventas anterior.
- En el campo Amount, puedes dejarlo vacío para devolver el 100% del dinero, o especificar una cantidad parcial.
- En el campo Reason, selecciona “Requested by customer”.
Conecta la salida:
- Conecta la salida success del componente Stripe Refund a un componente condicional.
- Si es True, envía un correo al cliente confirmando la devolución.
- Si es False, notifica al equipo de soporte para revisar el error.

Consejos y Mejores Prácticas

Verifica el Estado: Antes de intentar recuperar o listar reembolsos, asegúrate de que el Charge ID (el pago original) exista y sea válido.
Moneda Correcta: Recuerda que el campo Amount debe estar en la unidad más pequeña (centavos). Si quieres devolver $10.50 USD, debes ingresar 1050.
Uso de “Mode”: Utiliza el campo Mode para controlar si quieres una acción rápida sobre un solo elemento o una vista más amplia de tus datos. Esto ayuda a mantener tus flujos limpios y eficientes.
Documentación: Siempre intenta usar el campo Reason para categorizar los reembolsos. Esto facilitará tus reportes de finanzas y auditorías futuras.

Consideraciones de Seguridad

Protección de Credenciales: Asegúrate de usar siempre credenciales seguras y restrictivas en la sección de configuración de Stripe API. No compartas estas claves por canales no seguros.
Auditoría: El uso del campo Reason ayuda a mantener un registro claro de por qué se devuelven los fondos, lo cual es importante para la seguridad financiera y el cumplimiento de normas internas.