Saltearse al contenido
Nappai Documentation

Stripe Customer Card

Este componente actúa como el puente entre tu flujo de trabajo y Stripe, el sistema de pagos líder mundial. Su función principal es gestionar las tarjetas de crédito o débito asociadas a un cliente específico.

Imagina que tienes una base de datos de clientes. Este componente te permite tomar esa información y, mediante automatización, gestionar las formas de pago de esas personas: desde guardar una nueva tarjeta para que puedan comprar luego, hasta verificar el estado de una tarjeta existente o eliminar una cuando ya no es segura o el cliente la cancela.

¿Cómo funciona?

El componente funciona comunicándose automáticamente con la API de Stripe. Para hacerlo, utiliza una credencial de seguridad que tú has configurado previamente en Nappai.

Cuando ejecutas este nodo, le dices a Stripe qué quieres hacer con una tarjeta específica (añadirla, verla o borrarla) proporcionando dos datos clave:

  1. Quién es el cliente (Customer ID).
  2. Qué tarjeta queremos gestionar (Card ID o los detalles del token).

El sistema envía esta información de forma segura a Stripe, procesa la solicitud y te devuelve el resultado. Este resultado puede ser la confirmación de que la tarjeta se guardó correctamente, los detalles actualizados de la tarjeta o una indicación de que se eliminó exitosamente.

Conexión y Credenciales

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

  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 tu clave API secreta (Secret Key).
  3. 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. Ten en cuenta que algunos campos solo aparecen según la operación que elijas:

  • Operation: Permite seleccionar qué acción deseas realizar. Las opciones disponibles son:

    • By ID: Recupera los detalles de una tarjeta específica utilizando su ID.
    • All: Lista todas las tarjetas de pago asociadas a ese cliente.

  • Mode: Define cómo se procesará la información.

    • By ID: Se utilizará para recuperar un registro específico de la lista.
    • All: Se utilizará para listar múltiples registros.

  • Customer ID: Es el identificador único del cliente en Stripe (generalmente empieza por cus_...). Es necesario para identificar a qué persona se le va a añadir, buscar o borrar una tarjeta.

  • Card ID: Es el identificador único de la tarjeta específica (generalmente empieza por card_...). Este campo es necesario si quieres obtener detalles de una tarjeta concreta o eliminarla. No es necesario si solo estás listando todas las tarjetas o si acabas de añadir una nueva (ya que Stripe te dará el nuevo ID).

  • Source Token: Es un código seguro que representa los datos de la tarjeta. Para añadir una tarjeta nueva, no se usan los números directamente por seguridad, sino que se genera un “token” (ej. tok_visa) desde otro paso seguro. Este campo es requerido cuando vas a añadir una nueva tarjeta.

Salidas

Una vez que el componente ejecuta la operación, devuelve información que puedes usar en pasos posteriores de tu automatización:

  • Datos de la Tarjeta: Un objeto que contiene toda la información relevante de la tarjeta (si fue añadida, recuperada o listada). Esto incluye el ID de la tarjeta, la marca (Visa, Mastercard, etc.), los últimos 4 dígitos y la fecha de expiración.
  • Estado de la Operación: Un valor (verdadero/falso) que indica si la acción se realizó con éxito o si hubo algún error.
  • Mensajes de Error: Si algo sale mal (por ejemplo, si el cliente no existe), aquí encontrarás detalles sobre el error para poder solucionarlo.

Ejemplo de Respuesta JSON

Si tienes éxito al recuperar una tarjeta específica, la salida podría verse así: json { “id”: “card_1N2o3p4q5r6s7t”, “object”: “card”, “brand”: “Visa”, “country”: “US”, “exp_month”: 12, “exp_year”: 2025, “last4”: “4242”, “cvc_check”: “pass”, “name”: “Juan Pérez” }

Conectividad

Este componente suele conectarse lógicamente de la siguiente manera en un flujo de automatización:

  1. Entrada: Recibe datos de clientes desde componentes como “Get Customer” (Obtener Cliente) o “Search Customer”. Esto asegura que estás trabajando con el cliente correcto (Customer ID).
  2. Salida: Sus datos de salida (como el ID de la tarjeta añadida) suelen conectarse a:
    • Componentes de Facturación: Para cobrar al cliente usando esa nueva tarjeta.
    • Bases de Datos: Para guardar el historial de tarjetas de pago del cliente.
    • Notificaciones: Para informar al usuario o al administrador que la tarjeta ha sido registrada o eliminada.

Ejemplo de Uso

Escenario: Registrar la tarjeta de pago de un nuevo cliente

  1. Tienes un flujo que recibe datos de un nuevo usuario que se registró en tu plataforma.
  2. Usas un componente seguro para convertir los datos de la tarjeta de ese usuario en un Source Token.
  3. Conectas ese token al componente Stripe Customer Card.
  4. En el campo Operation, seleccionas la opción adecuada (dependiendo de cómo esté configurado tu flujo, a menudo requiere añadir la tarjeta). Nota: Dado que la operación principal es gestión, en este flujo asegurarías que el modo esté configurado para añadir o gestionar la tarjeta.
  5. En Customer ID, conectas el ID del cliente nuevo.
  6. En Source Token, conectas el token generado en el paso 2.
  7. El sistema añade la tarjeta al perfil del cliente en Stripe.
  8. La salida te devuelve el ID de la nueva tarjeta, que puedes guardar en tu base de datos para futuras cobranzas.

Consejos y Mejores Prácticas

  • Seguridad Primero: Nunca introduzcas los números reales de las tarjetas directamente en los campos visibles. Siempre usa el “Source Token” proporcionado por los métodos seguros de Stripe para manejar datos sensibles.
  • Validación de Clientes: Asegúrate de que el Customer ID sea válido antes de intentar operar con sus tarjetas. Si el cliente no existe, la operación fallará.
  • Uso del Modo Mapeo: Aprovecha el “Mapping Mode” para crear flujos dinámicos. Por ejemplo, en lugar de escribir fijo un ID de cliente, mapea el ID obtenido de un paso anterior que busca al usuario por su email.
  • Gestión de Errores: Siempre verifica la salida de “Estado” o “Error” en el siguiente paso de tu flujo. Si una tarjeta no se pudo añadir, tu automatización podría necesitar notificar al usuario o intentar de nuevo.

Consideraciones de Seguridad

  • Claves API: Utiliza siempre la credencial configurada en Nappai. Nunca expongas tus claves secretas de API en el código visible de tus flujos.
  • Tokens: Para añadir tarjetas, es obligatorio usar tokens (Source Token). Esto evita que los datos sensibles de las tarjetas de crédito atraviesen tu servidor o tus flujos de automatización en texto plano.
  • Acceso Restringido: Asegúrate de que solo los flujos autorizados tengan acceso a la credencial de Stripe API para evitar manipulación no autorizada de métodos de pago.