Saltar al contenido principal

Introducción

🎯 ¿Qué hace este módulo?​

El módulo de Payments te permite gestionar el procesamiento de pagos y transacciones para tu tienda de comercio electrónico. Trabajar con pagos y transacciones es una parte importante de cualquier proyecto de comercio electrónico. Se integra con pasarelas de pago como Stripe para manejar sesiones de pago, seguimiento de transacciones y gestión del estado de los pagos.

Piénsalo como tu sistema de gestión de pagos: configuras cuentas de pago en el panel de administración de OneEntry (Payments > Accounts), creas múltiples cuentas para diferentes tipos de pagos, como conectar un sistema de pago o agregar pagos en efectivo, y este módulo se encarga de la creación de sesiones de pago, seguimiento de estados y gestión de transacciones.

📖 Explicación Simple​

Cada aplicación de comercio electrónico necesita un procesamiento de pagos seguro:

  • 💳 Aceptar Pagos - Tarjetas de crédito, tarjetas de débito, billeteras digitales
  • 🔒 Procesamiento Seguro - Manejo de pagos conforme a PCI
  • 🔄 Estado del Pago - Seguimiento de pendientes, completados, fallidos, reembolsados
  • 💰 Reembolsos - Procesar reembolsos totales o parciales
  • 📊 Historial de Pagos - Ver todas las transacciones
  • 🔗 Integración de Pasarelas - Stripe, PayPal, pasarelas personalizadas

El problema con el manejo manual de pagos:

Problemas:

  • 🔒 Riesgo de seguridad - Almacenamiento de datos sensibles de tarjetas
  • 📋 Cumplimiento de PCI - Certificación costosa requerida
  • 💸 Sin seguimiento de reembolsos - Gestión manual de reembolsos
  • 🔄 Sin historial de pagos - Difícil de rastrear transacciones

La solución de Payments:

Beneficios:

  • 🔒 Conforme a PCI - Pagos seguros tokenizados
  • 📊 Seguimiento de pagos - Historial completo de transacciones
  • 🔄 Reembolsos automáticos - Procesamiento de reembolsos fácil
  • 💸 Múltiples pasarelas - Stripe, PayPal, personalizadas

✨ Conceptos Clave​

¿Qué es un Pago?​

Un Pago es un registro de transacción financiera que contiene:

  • Método de Pago - Tarjeta, PayPal, transferencia bancaria
  • Monto - Monto de la transacción y moneda
  • Referencia de Pedido - ID de pedido asociado
  • Estado del Pago - Pendiente, completado, fallido, reembolsado
  • Detalles de la Pasarela - ID de transacción de Stripe, referencia de PayPal
  • Información del Cliente - Detalles de facturación
  • Tiempos - Fechas de creación, procesamiento, finalización

Tipos de Cuentas Disponibles​

TipoCuándo UsarConfiguración Requerida
StripeConectar el sistema de pago Stripe a tu proyectoCuenta de Stripe, URLs
PersonalizadoSistemas de pago alternativos o pagos en efectivoConfiguración personalizada

Ciclo de Vida del Pago​

1. Crear cuenta de pago en el panel de administración
   (Configurar cuenta de Stripe o personalizada)
   ↓
2. El cliente realiza un pedido
   (Pedido creado en el módulo de Orders)
   ↓
3. Crear sesión de pago
   (Payments.createSession(orderId, type))
   ↓
4. El cliente es redirigido a la URL de pago
   (pago de Stripe o página de pago personalizada)
   ↓
5. El cliente completa el pago
   (Pago procesado por la pasarela)
   ↓
6. Estado del pago actualizado
   (esperando → pendiente → pagado/cancelado/expirado)
   ↓
7. Notificación recibida
   ↓
8. Estado del pedido sincronizado
   (Estado del pago vinculado al estado del pedido)

Estados de Pago​

El sistema incluye cuatro estados de pago preestablecidos que indican el estado de la transacción que se está procesando:

EstadoSignificadoCuándo Ocurre
PendienteEstado inicial de la transacciónSesión de pago recién creada
PagadoTransacción completada con éxitoPago confirmado por la pasarela
CanceladoTransacción fue canceladaEl cliente canceló el pago
ExpiradoEl período de validez de la transacción terminóSe superó el tiempo de espera

Importante: En la configuración de pagos, no puedes crear ni modificar estados. Sin embargo, puedes vincular estos estados de pago preestablecidos a los estados de almacenamiento de pedidos para habilitar la sincronización automática entre los sistemas de pago y de pedidos.

Métodos de Pago​

MétodoDescripciónSoporte de Pasarela
credit_cardVisa, Mastercard, AmexStripe, PayPal
debit_cardTarjetas de débitoStripe, PayPal
paypalCuenta de PayPalPayPal
bank_transferTransferencia bancaria, ACHPersonalizado
apple_payBilletera Apple PayStripe
google_payBilletera Google PayStripe
cash_on_deliveryPago contra entregaN/A

¿Por Qué Usar el Módulo de Payments?​

BeneficioDescripción
Cumplimiento de PCIProcesamiento de pagos seguros tokenizados
Integración de PasarelasStripe, PayPal integrados
Seguimiento de PagosHistorial completo de transacciones
Gestión de ReembolsosReembolsos totales/parciales fáciles
Protección contra FraudeDetección de fraude integrada
3D SecureSoporte para autenticación SCA
Multi-MonedaSoporte para múltiples monedas

📋 Lo Que Necesitas Saber​

Las Cuentas de Pago se Crean en el Panel de Administración​

No puedes crear cuentas de pago a través del SDK: se crean en el panel de administración de OneEntry:

Panel de Administración de OneEntry → Payments → Accounts → Crear Cuenta → Completar Formulario → Hacer clic en "Agregar"

Proceso de Creación:

  • Completa el formulario con tres campos requeridos:
    • Nombre - Identificador de cadena no único
    • Tipo - Seleccionado del menú desplegable: "Stripe" o "Personalizado"
    • Token - Identificador de cadena único
  • Haz clic en "Agregar" para crear la cuenta

Gestión de Cuentas:

  • Edición - Selecciona la cuenta, haz clic en el ícono de editar, modifica nombre/tipo/token/parámetros de Stripe
  • Ocultar - Haz clic en el ícono de ojo para ocultar cuentas de las selecciones de configuración de almacenamiento de pedidos
  • Eliminación - Selecciona la cuenta, haz clic en el ícono de eliminar, confirma la eliminación

El SDK es para obtener cuentas de pago y crear sesiones de pago, no para gestionar cuentas.

Tipos de Cuentas de Pago​

Hay dos tipos de cuentas de pago disponibles:

TipoDescripción
StripeElige este tipo para conectar el sistema de pago Stripe
PersonalizadoPara sistemas de pago alternativos o pagos en efectivo

Configuración específica de Stripe:

  • URL de éxito - URL de redirección después del pago exitoso
  • URL de cancelación - URL de redirección si se cancela el pago
  • Duración de la sesión - Tiempo de espera de la sesión en minutos

Sincronización de Estados de Pago​

Los estados de pago se pueden vincular a los estados de almacenamiento de pedidos:

Panel de Administración de OneEntry → Payments → Statuses → Seleccionar Almacenamiento de Pedidos → Mapear Estados → Guardar

Flujo de trabajo de mapeo de estados:

  1. Navega a la subsección de Estados dentro de Payments
  2. Selecciona el sistema de almacenamiento de pedidos deseado
  3. Mapea cada estado de pago preestablecido al valor correspondiente del estado de almacenamiento de pedidos
  4. Verifica que todos los mapeos sean precisos
  5. Haz clic en Guardar para aplicar los cambios

Esto permite actualizaciones automáticas de estado en los registros de pedidos cuando cambian los estados de pago.

Nunca Almacenes Datos de Tarjeta en Crudo​

CRÍTICO: Nunca almacenes números de tarjetas de crédito, CVV o fechas de caducidad completas.

¿Por qué?

  • El cumplimiento de PCI DSS requiere un manejo seguro
  • Almacenar datos de tarjetas te expone a responsabilidad
  • OneEntry nunca almacena detalles de tarjetas en crudo

💡 Notas Importantes​

Las Cuentas de Pago se Crean en el Panel de Administración​

Recuerda: El SDK es para obtener cuentas de pago y crear sesiones, no para crear cuentas.

Para crear/editar cuentas de pago: Usa el Panel de Administración de OneEntry.

Gestión de Cuentas de Pago​

Creando cuentas en el panel de administración:

  1. Navega a Payments > Accounts
  2. Completa el formulario con Nombre, Tipo y Token
  3. Para cuentas de Stripe, configura la URL de Éxito, URL de Cancelación y Duración de la Sesión
  4. Haz clic en "Agregar" para crear

Gestionando cuentas:

  • Editar - Modifica nombre, tipo, token o parámetros específicos de Stripe
  • Ocultar - Haz clic en el ícono de ojo para ocultar de la configuración de almacenamiento de pedidos (no elimina)
  • Eliminar - Elimina cuentas no utilizadas por completo

Importante: Solo se pueden eliminar cuentas no utilizadas.

Configuración de Estados de Pago​

Importante: No puedes crear o modificar estados de pago en el panel de administración. El sistema tiene cuatro estados preestablecidos: Pendiente, Pagado, Cancelado, Expirado.

Flujo de trabajo de sincronización de estados:

  1. Navega a Payments > Statuses
  2. Selecciona el sistema de almacenamiento de pedidos
  3. Mapea los estados de pago preestablecidos a los estados de almacenamiento de pedidos
  4. Haz clic en Guardar para aplicar los cambios

Esto permite actualizaciones automáticas del estado del pedido cuando cambian los estados de pago.

Tipos de Sesión​

Hay dos tipos de sesión disponibles:

TipoDescripción
sessionCrea una página de pago de Stripe Checkout con enlace de pago
intentCrea una intención de pago para procesamiento de pago directo

Seguridad Primero​

🔒 Reglas de seguridad críticas:

  • Nunca almacenes datos de tarjeta en crudo - Usa tokenización
  • Usa solo HTTPS - Todas las páginas de pago deben ser SSL
  • Valida en el servidor - Nunca confíes en datos del lado del cliente
  • Registra transacciones - Mantén un rastro de auditoría
  • Maneja PII con cuidado - Protege los datos del cliente

Cumplimiento de PCI​

✅ OneEntry maneja el cumplimiento de PCI por ti:

  • Procesamiento de pagos tokenizados
  • Integración de pasarela segura
  • Sin almacenamiento de datos de tarjeta en crudo
  • Transmisión encriptada

Tu responsabilidad:

  • Usa HTTPS en las páginas de pago
  • No registres datos sensibles
  • Sigue las mejores prácticas de seguridad

Sondeo de Estados de Pago​

Para pagos asíncronos, sondea para actualizaciones de estado:

Limitaciones de Reembolsos​

Reglas importantes de reembolsos:

  • Solo se pueden reembolsar pagos completados
  • Los reembolsos parciales no deben exceder el monto original
  • Algunas pasarelas tienen límites de tiempo (por ejemplo, 180 días)
  • Los reembolsos son asíncronos (pueden tardar días)

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getAccounts()Obtener todas las cuentas de pagoListar métodos de pago disponibles
getAccountById()Obtener cuenta de pago por IDObtener detalles de cuenta específica
createSession() 🔐Crear sesión de pagoGenerar enlace de pago para el pedido
getSessions() 🔐Obtener todas las sesiones de pago (paginadas)Ver historial de sesiones de pago
getSessionById() 🔐Obtener sesión de pago por IDVerificar estado de sesión específica
getSessionByOrderId() 🔐Obtener sesión de pago por ID de pedidoEncontrar pago para pedido específico

🔐 = Requiere autorización

❓ Preguntas Comunes (FAQ)​

¿Cómo configuro los pagos de Stripe?​

Crea una cuenta de pago en el panel de administración con el tipo "Stripe", luego configura la URL de Éxito, la URL de Cancelación y la Duración de la Sesión. Usa createSession() para generar enlaces de pago que redirijan a los clientes a Stripe Checkout.

¿Cuál es la diferencia entre los tipos de pago de sesión e intención?​

Una sesión crea una página de pago de Stripe Checkout con una URL de redirección, ideal para páginas de pago alojadas. Una intención crea una intención de pago para la integración de formularios de pago personalizados directamente en tu aplicación.

¿Puedo soportar múltiples métodos de pago?​

¡Sí! Crea múltiples cuentas de pago (Stripe, personalizadas, pago contra entrega) en el panel de administración. Cada pedido puede usar una cuenta de pago diferente según la selección del cliente.

¿Cómo vinculo los estados de pago a los estados de pedido?​

En el panel de administración, ve a Payments > Statuses, selecciona tu almacenamiento de pedidos y mapea los cuatro estados de pago preestablecidos (Pendiente, Pagado, Cancelado, Expirado) a los estados de pedido correspondientes. Esto habilita la sincronización automática.

¿Qué sucede si una sesión de pago expira?​

Las sesiones de pago tienen una duración configurable (establecida en la configuración de la cuenta). Si un cliente no completa el pago dentro de este tiempo, el estado de la sesión cambia a "Expirado" y necesitará crear una nueva sesión de pago.

🎓 Mejores Prácticas​

  • Usa tokenización - Siempre tokeniza tarjetas con Stripe.js
  • Valida montos - Verifica totales en el servidor, no solo en el cliente
  • Maneja errores con gracia - Mensajes de error claros para los usuarios
  • Registra transacciones - Mantén un rastro de auditoría de todos los pagos
  • Usa webhooks - Escucha actualizaciones de estado de pago
  • Prueba con claves de prueba - Usa el modo de prueba de Stripe antes de producción
  • Maneja 3D Secure - Implementa el flujo de autenticación SCA
  • Almacena IDs de transacción - Mantén referencias de pasarela para disputas

Más información sobre pagos en el panel de administración de OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/payments

Definición del módulo Payments​

El módulo de Payments gestiona el procesamiento de pagos y transacciones. Proporciona herramientas para trabajar con cuentas de pago, crear sesiones de pago y rastrear estados de pago.


const { Payments } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Documentación Relacionada​