Saltar al contenido principal

Introducción

Crea sesiones de pago y rastrea transacciones a través de las pasarelas configuradas en tu proyecto.

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

🎯 ¿Qué hace este módulo?​

El módulo de Payments te permite crear sesiones de pago y rastrear transacciones para tu tienda. Configuras cuentas de pago en el panel de administración (Payments > Accounts) — Stripe o personalizadas — y este módulo crea una sesión de pago para un pedido, devuelve el enlace de pago de la pasarela y te permite leer el historial y el estado de la sesión.

El SDK obtiene cuentas de pago y crea sesiones de pago; las cuentas y los estados se configuran en el panel de administración.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Crea una sesión de pago para un pedido y redirige al cliente a la pasarela (se requiere autenticación):

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");

console.log(session.id, session.status, session.paymentUrl);

// Send the customer to the gateway checkout page.
window.location.href = session.paymentUrl;

✨ Conceptos Clave​

¿Qué es una sesión de pago?​

Una sesión de pago (ISessionEntity) es un registro que contiene:

  • type — 'session' o 'intent'
  • status — cadena de estado de pago de forma libre (por ejemplo, "waiting", "completed")
  • paymentAccountId — la cuenta configurada utilizada
  • orderId — el pedido asociado
  • paymentUrl — enlace de pago de la pasarela (o null)
  • createdDate / updatedDate — marcas de tiempo

Tipos de sesión​

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

Tipos de cuenta​

TipoCuándo UsarConfiguración Requerida
StripeConectar el sistema de pago de StripeCuenta de Stripe, URLs
CustomSistemas de pago alternativos o pagos en efectivoConfiguración personalizada

Estados de pago​

El status de una sesión es una cadena de forma libre establecida a partir del resultado de la pasarela, no un enum fijo. Valores comunes:

EstadoSignificado
waitingSesión creada, esperando pago
completedPago confirmado por la pasarela

No puedes crear o modificar estados de pago en el panel de administración. Sin embargo, puedes mapear los estados de pago a los estados de almacenamiento de pedidos para que el estado del pedido se actualice automáticamente cuando cambie el estado de pago.

Ciclo de vida del pago​

1. Configure a payment account in the admin panel (Stripe or custom)
   ↓
2. Customer places an order (Orders module)
   ↓
3. Create a payment session  →  Payments.createSession(orderId, type)
   ↓
4. Redirect the customer to session.paymentUrl
   ↓
5. Customer completes payment at the gateway
   ↓
6. Session status reflects the gateway result (e.g. "waiting" → "completed")
   ↓
7. Mapped order status is updated automatically

📋 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 — créalas y edítalas en el panel de administración de OneEntry (Payments > Accounts), proporcionando Nombre, Tipo (Stripe o Personalizado) y Token. Para cuentas de Stripe también configuras Success URL, Cancel URL y Session lifetime. El SDK es para obtener cuentas y crear sesiones.

Sincronización de estados​

Los estados de pago están mapeados a los estados de almacenamiento de pedidos en el panel de administración (Payments > Statuses → seleccionar almacenamiento de pedidos → mapear estados → guardar). Esto permite actualizaciones automáticas del estado del pedido cuando cambia el estado de pago.

Nunca almacenes datos de tarjeta en bruto​

Nunca almacenes números de tarjetas de crédito, CVV o fechas de caducidad completas. El pago es manejado por la pasarela (Stripe), lo que te mantiene fuera del alcance para almacenar datos de tarjetas; OneEntry nunca almacena detalles de tarjetas en bruto.

Los reembolsos viven en el módulo de Orders​

El módulo de Payments no tiene métodos de reembolso. Los reembolsos son manejados por el módulo de Orders a través de createRefundRequest(), cancelRefundRequest() y getRefunds().

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getAccounts() 🔐Obtener todas las cuentas de pagoListar cuentas de pago configuradas
getAccountById() 🔐Obtener cuenta de pago por IDObtener detalles de cuenta específica
createSession() 🔐Crear sesión de pagoGenerar enlace de pago para 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 tipo "Stripe", luego configura Success URL, Cancel URL y Session lifetime. Usa createSession() con tipo "session" para generar un enlace que redirija 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 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 cuentas de pago?​

Sí. Crea múltiples cuentas de pago (Stripe o personalizadas) en el panel de administración. Cada pedido puede usar una cuenta diferente a través de su paymentAccountIdentifier.

¿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 estados de pago a los estados de pedido. Esto permite la sincronización automática.

¿Cómo emito un reembolso?​

Los reembolsos no son parte del módulo de Payments. Usa el módulo de Orders: createRefundRequest() para solicitar un reembolso, cancelRefundRequest() para cancelar una solicitud y getRefunds() para listarlos.

🎓 Mejores Prácticas​

  • Autentica primero — cada método de Payments requiere un usuario autorizado (ver AuthProvider).
  • Redirige a paymentUrl después de crear una sesión, y maneja las URL de retorno de la pasarela en tu aplicación.
  • Lee el estado de la sesión, no del cliente — verifica el status de la sesión (o getSessionByOrderId()) para confirmar el pago.
  • Mapea los estados de pago a los estados de pedido para que el estado del pedido se mantenga sincronizado automáticamente.
  • Prueba con claves de prueba de Stripe antes de pasar a producción.

🔗 Documentación Relacionada​