📘 Manual de Integración Frontend

Guía oficial del flujo de pagos y seguridad de datos.

🔄 Diagrama de Flujo Global

sequenceDiagram participant User as Usuario participant Front as Tu Frontend participant API as SOMARPAY API participant Prov as Proveedor (WebPay/MP) User->>Front: Clic en "Pagar" Front->>API: POST /checkout API-->>Front: JSON { action: "REDIRECT", target_url: "..." } Note over Front, User: ⚠️ NO pedir datos de tarjeta aquí Front->>User: Redireccionar a target_url User->>Prov: Ingresa Tarjeta (Seguro) Prov-->>User: Procesa Pago Prov->>User: Redirecciona a return_url User->>Front: Vuelve a tu sitio Front->>API: GET /payments/{id} (Polling) API-->>Front: Status: APPROVED Front->>User: Muestra "Pago Exitoso"

📝 Detalle de Pasos

1. Inicio de Transacción

El frontend envía la orden de compra al backend, y este llama a SOMARPAY.

Respuesta Típica:

{
  "payment_id": "pay_123",
  "action": "REDIRECT",
  "target_url": "https://webpay3gint.transbank.cl/...",
  "token": "01ab23cd..."
}

2. Redirección

El frontend debe obedecer el campo action.

  • Si action es REDIRECT: Redirigir el navegador del usuario a target_url.
  • Importante: No renderizar formularios de tarjeta propios.

3. Ingreso de Datos (El paso crítico)

🛑 Diferencia entre Producción y Simulador

En Producción (Real)

El usuario está en una página segura de Transbank, MercadoPago, etc.

  • Tú NO ves los datos de la tarjeta.
  • Tú NO envías el JSON de tarjeta.
  • La seguridad es responsabilidad del proveedor.

En el Simulador (Desarrollo)

Para fines de depuración, el simulador muestra un paso llamado "Usuario Ingresa Datos" con el siguiente JSON:

{
  "card_number": "•••• •••• •••• 4532",
  "expiry": "12/26",
  "cvv": "•••",
  "cardholder": "SIMULADOR SOMARPAY"
}
Nota: Este JSON es solo una representación visual de los logs del simulador. NUNCA intentes construir o enviar este JSON en tu aplicación real.

4. Confirmación

Una vez que el usuario paga, es redirigido a tu return_url.

  1. Muestra una pantalla de "Verificando...".
  2. Consulta el estado del pago a tu backend.
  3. Tu backend consulta a SOMARPAY o espera el Webhook.

📋 Checklist para Frontend

  • No crear formularios de tarjeta: Delegar a URL externa.
  • Manejar redirección: Usar window.location.href.
  • Página de Retorno: Ruta lista para recibir al usuario (success).
  • Página de Cancelación: Ruta para manejo de errores/anulación.