Saltearse al contenido
Nappai Documentation

PayPal Order

El componente PayPal Order es una herramienta diseñada para facilitar la integración de pagos de PayPal en tus flujos de automatización dentro de Nappai. Su función principal es actuar como un puente seguro entre tu sistema y la plataforma de pagos de PayPal, permitiéndote gestionar transacciones comerciales de manera eficiente.

Puedes utilizar este componente para realizar dos tareas fundamentales: crear nuevas órdenes de pago para clientes o recuperar y verificar el estado de una orden ya existente. Al hacerlo, automatizas procesos como la validación de precios, la verificación de pagos y la gestión de estados de pedido, todo sin necesidad de escribir código complejo.

¿Cómo funciona?

Internamente, este componente se comunica con la API de “Orders V2” de PayPal. Para que esta comunicación sea posible, el componente sigue un proceso estructurado:

  1. Autenticación Segura: Utiliza las credenciales que configuremos previamente (Client ID y Client Secret) para obtener un token de acceso seguro. Esto asegura que solo se realicen operaciones autorizadas en tu cuenta de PayPal.
  2. Ejecución de la Solicitud: Dependiendo de la acción que elijas, el componente enviará la información necesaria a los servidores de PayPal:
    • Crear una orden: Envia el monto, la moneda, la descripción y la intención de pago (si quieres cobrar inmediatamente o solo autorizar el fondo).
    • Obtener una orden: Utiliza el ID único de la orden para consultar su estado actual (por ejemplo, si está “aprobada”, “completada” o “pendiente”).
  3. Retorno de Datos: Una vez que PayPal procesa la solicitud, el componente te devuelve la información relevante, como el ID de la orden generada o el estado actual de la transacción, listo para ser utilizado en el siguiente paso de tu flujo de trabajo.

Conexión y Credenciales

Para que este componente funcione correctamente, es necesario haber configurado una conexión segura con tu cuenta de PayPal. Sin esta configuración, no podrás interactuar con su API.

Sigue estos pasos para establecer la conexión:

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo PayPal API y completa los campos requeridos (Client ID y Client Secret obtenidos desde el panel de desarrolladores de PayPal).
  3. En tu flujo de trabajo, al configurar este nodo, selecciona la credencial guardada en el campo de entrada Credential.

Entradas

Modo de Mapeo (Mapping Mode)

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. Cada campo puede estar visible en diferentes operaciones:

  • Operation: Permite seleccionar la acción principal a realizar con la orden de PayPal (por ejemplo, crear una nueva orden o recuperar los detalles de una existente).
  • Order ID: El identificador único de la orden de PayPal. Es necesario cuando deseas recuperar o verificar una orden que ya fue creada previamente.
  • Intent: Define la intención del pago. Puedes elegir entre recolectar el pago inmediatamente o mantener los fondos reservados para una futura autorización.
  • Amount: El monto del pago expresado como un número decimal (ejemplo: “10.00”). Este campo es esencial para definir cuánto se cobrará.
  • Currency: El código de moneda de tres letras según el estándar ISO (por ejemplo: “USD” para dólares estadounidenses o “EUR” para euros).
  • Description: Una breve descripción del producto o servicio. Esta información será visible en el recibo del cliente y en tu panel de PayPal.

Salidas

Una vez que el componente ha procesado la solicitud, te proporciona información clave para continuar con tu flujo de automatización. Las salidas más importantes incluyen:

  • Order ID: El identificador único generado por PayPal. Es crucial para identificar la transacción en registros futuros o para verificar su estado más tarde.
  • Purchase Units: Detalles específicos sobre las unidades compradas, incluyendo montos y descripciones.
  • Links: Una lista de enlaces (URLs) que indican las siguientes acciones posibles, como el enlace para que el cliente apruebe el pago.
  • Status: El estado actual de la orden (por ejemplo: CREATED, APPROVED, COMPLETED), lo que te permite tomar decisiones condicionales en tu flujo (ej. “Si el estado es COMPLETADO, envía el producto”).

Ejemplo de Respuesta JSON

El siguiente bloque muestra un ejemplo de la estructura de datos que podrías recibir al crear una orden exitosamente. Estos datos pueden ser utilizados en los siguientes pasos de tu flujo. json { “id”: “5O190127TN364715T”, “status”: “CREATED”, “intent”: “CAPTURE”, “purchase_units”: [ { “reference_id”: “default”, “amount”: { “currency_code”: “USD”, “value”: “100.00” } } ], “links”: [ { “href”: “https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T”, “rel”: “self”, “method”: “GET” }, { “href”: “https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T”, “rel”: “approve”, “method”: “GET” } ] }

Conectividad

Este componente es una pieza central en cualquier flujo que implique transacciones financieras. Lógicamente, se conecta de la siguiente manera:

  • Entradas: Suele recibir datos de componentes que gestionan el carrito de compras, el cálculo de totales (monto y moneda) o la identidad del cliente (para generar la descripción de la orden).
  • Salidas: El Order ID generado suele ser alimentado a componentes siguientes como PayPal Capture (para cobrar el pago) o PayPal Check (para verificar el estado). Los enlaces (links) de salida a menudo se utilizan para redirigir al usuario final a la página de pago de PayPal.

Ejemplo de Uso

Imagina que estás automatizando la venta de un producto digital.

  1. Primero, un componente calcula el total de la venta y obtiene el ID del cliente.
  2. Utilizas el componente PayPal Order con la operación Create.
  3. Configuras el Intent en CAPTURE para cobrar de inmediato.
  4. Introduces el Amount y seleccionas la Currency.
  5. Al ejecutar el flujo, el componente devuelve el Order ID y el enlace de pago.
  6. En el siguiente paso, usas ese Order ID en un componente de Capture para finalizar la transacción y enviar el producto digital al cliente.

Consejos y Mejores Prácticas

  • Prueba primero en Sandbox: Al configurar nuevas integraciones, asegúrate de que tu credencial de PayPal esté en modo “Sandbox” para evitar cargos reales mientras pruebas tu flujo.
  • Maneja los Estados: Siempre verifica el Status devuelto por el componente. No asumas que una orden creada es un pago completado; el cliente debe aprobarla en la pantalla de PayPal.
  • Descripciones Claras: Usa el campo Description para incluir referencias de pedido o nombres de clientes, lo que facilitará la conciliación de pagos más adelante.
  • Moneda Correcta: Asegúrate de que la Currency coincida con la configuración de tu cuenta de PayPal para evitar errores de validación.

Consideraciones de Seguridad

  • Protección de Credenciales: Nunca compartas tu Client ID ni tu Client Secret en texto plano. Utiliza siempre la sección de Credenciales de Nappai para almacenarlas de forma segura.
  • Validación de Entorno: Asegúrate de que estás utilizando el entorno correcto (Sandbox para pruebas, Live para producción) en la configuración de la credencial para evitar inconsistencias en los datos de tus órdenes.