Este repositorio resuelve todos estos casos. La implementación está auditada contra la referencia oficial de la API v1.2.

Características

Stack Tecnológico

Arquitectura

Arquitectura Hexagonal (Puertos y Adaptadores) organizada por scope de features:

src/
├── app/                              # Next.js App Router (capa de presentación)
│   ├── api/
│   │   ├── auth/[[...all]]/route.ts  # BetterAuth catch-all handler
│   │   └── webpay/
│   │       ├── checkout/route.ts     # POST — iniciar pago
│   │       ├── return/route.ts       # POST + GET — callback de Transbank
│   │       └── poll/route.ts         # GET — worker de recuperación (cron)
│   └── checkout/
│       ├── page.tsx                  # UI de checkout
│       ├── success/page.tsx          # Confirmación de pago (verifica BD)
│       └── error/page.tsx            # Pantalla de error
│
├── features/
│   ├── auth/                         # Módulo de autenticación
│   │   ├── auth.ts                   # Configuración de BetterAuth
│   │   └── infrastructure/
│   │       ├── email-service.ts           # Templates + envío de emails (Resend)
│   │       ├── upstash-secondary-storage.ts  # Adaptador Redis para sesiones
│   │       └── upstash-secondary-storage.test.ts
│   │
│   ├── webpay/                       # Módulo de pagos
│   │   ├── domain/
│   │   │   └── Transaction.ts        # Entidad + máquina de estados
│   │   ├── application/
│   │   │   └── transactionActions.ts # Casos de uso (Server Actions)
│   │   └── infrastructure/
│   │       ├── TransbankGateway.ts           # Adaptador HTTP → API Transbank
│   │       └── PrismaTransactionRepository.ts # Adaptador BD → Dominio
│   │
│   └── rate-limit/                   # Módulo de rate limiting
│       ├── domain/
│       │   ├── RateLimitGateway.ts    # Interfaz (intercambiable)
│       │   └── parseWindow.ts         # Parser de ventana compartido
│       └── infrastructure/
│           ├── UpstashRateLimitGateway.ts   # Adaptador Upstash
│           └── MemoryRateLimitGateway.ts    # Fallback para desarrollo
│
└── shared/
    ├── env.ts                        # Variables de entorno validadas con Zod
    ├── lib/prisma.ts                 # Singleton de Prisma client
    └── rate-limit.ts                 # Factory + helpers de rate limiting

Flujo de Datos

┌─────────────────────────────────────────────────────────────────────┐
│ 1. INICIAR                                                          │
│    checkout/page.tsx                                               │
│    └── initiateTransactionAction(amount)                            │
│        ├── Crear WebpayTransaction (INITIALIZED)                   │
│        ├── Persistir ANTES de llamada a red                        │
│        ├── TransbankGateway.createTransaction() → token + URL       │
│        ├── Guardar token en BD                                      │
│        └── redirect() → formulario de pago de Transbank             │
├─────────────────────────────────────────────────────────────────────┤
│ 2. CONFIRMAR (callback de Transbank)                                │
│    POST /api/webpay/return?token_ws=<token>                         │
│    └── confirmTransactionAction(token)                               │
│        ├── A) Normal: commitTransaction() → AUTHORIZED | REJECTED   │
│        ├── B) 422: getTransactionStatus() → fallback, sin FAILED    │
│        └── C) Ya terminal: idempotente, retornar estado actual      │
├─────────────────────────────────────────────────────────────────────┤
│ 3. RECUPERAR (Vercel Cron)                                          │
│    GET /api/webpay/poll  [Authorization: Bearer <CRON_SECRET>]      │
│    └── pollStaleTransactionsAction()                                 │
│        └── Buscar INITIALIZED > 10 min → getTransactionStatus()     │
└─────────────────────────────────────────────────────────────────────┘

Los 3 Escenarios de Return URL

Aquí es donde falla el 90% de las integraciones. Transbank puede llamar a la return_url de tres formas diferentes, y debe manejar todas:

[!IMPORTANT] Cuando el usuario cancela o hay timeout, token_ws NO está presente. Si solo maneja token_ws, está ignorando dos de los tres escenarios.

Máquina de Estados de Transacciones

                    ┌──────────┐
                    │ INITIALIZED │
                    └─────┬────┘
           ┌──────────────┼──────────────┬──────────────┐
           ▼              ▼              ▼              ▼
    ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ AUTHORIZED  │ │ REJECTED │ │ ABORTED  │ │  FAILED  │
    └──────┬──────┘ └──────────┘ └──────────┘ └──────────┘
           │
           ▼
    ┌──────────┐
    │ REVERSED │
    └──────────┘

[!CAUTION] Una transacción AUTHORIZED NUNCA puede revertirse a FAILED. Si Transbank ya cobró y tu sistema falla después, debe llamar a requestRefund(). Un rollback de estado es un desastre contable y una violación de las políticas de Transbank.

Tests

Suite de Tests

Ejecutar Tests

# Ejecutar todos los tests
bun run test

# Ejecutar con coverage
bunx vitest run --coverage

# Ejecutar un archivo específico
bunx vitest run src/features/webpay/domain/Transaction.test.ts

Arquitectura de Tests

• Tests unitarios: Entidades de dominio, máquina de estados, casos de uso — sin dependencias externas
• Tests de infraestructura: Adaptadores Upstash con fetch() mockeado — sin Redis real
• Tests de integración: Handlers de rutas API con gateways mockeados — sin Transbank/BD real

Seguridad

Autenticación (BetterAuth)

Rate Limiting

Variables de Entorno

• Todas las secrets validadas al startup con Zod (fail-fast)
• BETTER_AUTH_URL: sin default en producción (lanza error si falta)
• RESEND_API_KEY/RESEND_FROM_EMAIL: opcionales en dev, requeridas en producción
• Upstash: opcional en dev (fallback en memoria), requerido en producción

Inicio Rápido

Prerrequisitos

• Bun 1.x (o Node.js 20+)
• PostgreSQL 14+ (local o cloud — Neon recomendado)
• Cuenta activa en Portal de Desarrolladores Transbank

1. Clonar e instalar

git clone https://github.com/Lostovayne/WebpayPlus-in-Next16.git
cd WebpayPlus-in-Next16
bun install

2. Configurar variables de entorno

cp .env.ex