Flujo de Pagos Transbank - Ideas-Digitales/socomarca-backend GitHub Wiki

POST /api/orders/create-from-cart

1. El usuario envía una solicitud con su user_id
2. El sistema:
   • Verifica que el carrito no esté vacío
   • Calcula el subtotal sumando (precio × cantidad) de cada item
   • Crea una nueva orden con estado 'pending'
   • Crea los items de la orden basados en los items del carrito
   • Limpia el carrito del usuario
   • Todo esto se realiza en una transacción (si algo falla, se revierte todo)

• pending: Orden creada, pendiente de pago
• processing: Orden en proceso de pago
• on_hold: Orden en espera
• completed: Pago exitoso
• canceled: Orden cancelada
• refunded: Reembolso realizado
• failed: Pago fallido

POST /api/orders/pay

• Requiere order_id y user_id
• Verifica que:
  • La orden exista
  • Pertenezca al usuario
  • Esté en estado 'pending'

1. El sistema crea una transacción en Transbank con:

   • ID de la orden
   • ID del usuario
   • Monto total
   • URL de retorno

2. Se crea un registro en la tabla payments con:

   • order_id: ID de la orden
   • payment_method_id: ID del método de pago (Transbank)
   • auth_code: Inicialmente '1'
   • amount: Monto de la orden
   • response_status: 'pending'
   • response_message: JSON vacío
   • token: Token de la transacción
   • paid_at: null

1. El usuario es redirigido a la página de pago de Transbank
2. El usuario ingresa los datos de su tarjeta
3. Transbank procesa el pago y redirige al usuario a la URL de retorno

Es necesario enviar el token por POST

HTML de ejemplo

<div class="example mt-10">
    <p>Con el siguiente código se realiza la redirección: </p>
    <code class="block"><pre>
    <form method="post" action="https://webpay3gint.transbank.cl/webpayserver/initTransaction">
    <input type="text" name="token_ws" value=""/>
    <button type="submit">Enviar datos</button>
</form>

GET /api/webpay/return

1. El sistema:
   • Verifica el resultado de la transacción con Transbank
   • Actualiza el estado de la orden a 'completed'
   • Actualiza el registro de pago:
     • response_status: Estado de Transbank
     • response_message: Respuesta completa de Transbank
     • auth_code: Código de autorización
     • paid_at: Fecha y hora del pago

1. El sistema:
   • Actualiza el estado de la orden a 'failed'
   • Actualiza el registro de pago:
     • response_status: 'failed'
     • response_message: Mensaje de aborto
     • paid_at: null

1. El sistema:
   • Mantiene la orden en estado 'pending'
   • No actualiza el registro de pago

GET /api/webpay/status

• Permite consultar el estado de una transacción usando el token

POST /api/webpay/refund

• Permite realizar reembolsos de transacciones exitosas
• Requiere:
  • token: Token de la transacción
  • amount: Monto a reembolsar

• Almacena las órdenes
• Estados: pending, processing, on_hold, completed, canceled, refunded, failed

• Almacena los registros de pago
• Campos principales:
  • order_id: Relación con la orden
  • payment_method_id: Método de pago usado
  • auth_code: Código de autorización
  • amount: Monto
  • response_status: Estado de la respuesta
  • response_message: Mensaje de respuesta
  • token: Token de la transacción
  • paid_at: Fecha de pago

• Almacena los items de cada orden
• Relacionado con productos y órdenes

El sistema mantiene logs detallados de:

• Creación de transacciones
• Resultados de pagos
• Errores
• Actualizaciones de estado
• Reembolsos

• Todas las rutas de API requieren autenticación
• Se verifica la propiedad de las órdenes
• Se validan los estados antes de procesar pagos
• Se mantiene un registro completo de todas las transacciones
• Se utilizan transacciones de base de datos para mantener la integridad

¿Necesitas que profundice en algún aspecto específico de la documentación?