# MII-013: Pagos 7-Eleven

---
id: MII-013
type: Epic
status: Completado
priority: P1
phase: 3
story_points: 8
created_date: 2026-01-10
updated_date: 2026-01-13
simco_version: "4.0.0"
---

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | MII-013 |
| **Nombre** | Pagos 7-Eleven |
| **Fase** | 3 - Monetizacion |
| **Prioridad** | P1 |
| **Story Points** | 8 |
| **Estado** | Completado |

---

## 1. Descripcion

Implementar pagos en efectivo via 7-Eleven usando un agregador de pagos (como Conekta, OpenPay o similar) que soporte referencias 7-Eleven.

### Objetivo

Ampliar las opciones de pago en efectivo para usuarios que prefieren 7-Eleven sobre OXXO.

---

## 2. Requerimientos Relacionados

| RF | Descripcion | Prioridad |
|----|-------------|-----------|
| FR-102 | Pagos en 7-Eleven via agregador | P1 |
| FR-103 | Confirmacion de pago via webhooks | P0 |
| FR-104 | Reconciliacion de estados | P0 |
| FR-105 | Expiracion de referencia (24-72h) | P1 |

---

## 3. Criterios de Aceptacion

### AC-001: Generar Referencia
```gherkin
DADO que seleccione pago en 7-Eleven
CUANDO confirmo el pedido
ENTONCES recibo una referencia con:
  - Numero de referencia
  - Monto a pagar
  - Codigo de barras
  - Instrucciones de pago
  - Fecha de expiracion
```

### AC-002: Pago en Tienda
```gherkin
DADO que tengo una referencia valida
CUANDO pago en 7-Eleven
ENTONCES recibo un ticket de confirmacion
Y en minutos mis creditos se acreditan
Y recibo notificacion push
```

### AC-003: Similar a OXXO
```gherkin
DADO que el flujo es similar a OXXO
CUANDO genero una referencia 7-Eleven
ENTONCES la experiencia es consistente
Y puedo ver referencias pendientes
Y el voucher tiene el mismo formato
```

---

## 4. Tareas Tecnicas

| ID | Tarea | Estimacion | Estado |
|----|-------|------------|--------|
| T-001 | Investigar y seleccionar agregador | 1 SP | Completado |
| T-002 | Configurar agregador en backend | 2 SP | Completado |
| T-003 | Implementar generador de referencias | 2 SP | Completado |
| T-004 | Implementar webhook del agregador | 2 SP | Completado |
| T-005 | Adaptar UI para 7-Eleven | 1 SP | Completado |

---

## 5. Opciones de Agregador

| Agregador | Ventajas | Desventajas |
|-----------|----------|-------------|
| **Conekta** | Soporte MX, facil integracion | Costo por transaccion |
| **OpenPay** | Multiples cadenas | Documentacion limitada |
| **PayU** | Experiencia global | Menos enfoque MX |
| **Stripe** | Ya integrado | Solo OXXO, no 7-Eleven |

**Recomendacion:** Conekta (mejor soporte para Mexico y cadenas de conveniencia)

---

## 6. Flujo Similar a OXXO

```
┌─────────────────────────────────────────────────────────────────┐
│                 FLUJO DE PAGO 7-ELEVEN                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  APP                        7-ELEVEN               AGREGADOR    │
│   │                            │                        │       │
│   │ 1. Seleccionar 7-Eleven    │                        │       │
│   │─────────────────────────────────────────────────────▶       │
│   │                            │     Referencia         │       │
│   │◀─────────────────────────────────────────────────────       │
│   │    Voucher                 │                        │       │
│   │                            │                        │       │
│   │ 2. Mostrar voucher         │                        │       │
│   │                            │                        │       │
│   │              3. Usuario va │                        │       │
│   │                a 7-Eleven  │                        │       │
│   │                    ───────▶│                        │       │
│   │                            │ 4. Paga                │       │
│   │                            │────────────────────────▶       │
│   │                            │                        │       │
│   │◀─────────────────────────────────────────────────────       │
│   │         Webhook            │     5. Confirma        │       │
│   │                            │                        │       │
│   │ 6. Acreditar creditos      │                        │       │
│   │                            │                        │       │
└─────────────────────────────────────────────────────────────────┘
```

---

## 7. Modelo de Datos

Reutiliza la tabla `payment_orders` con:

```sql
-- Campos adicionales en metadata para 7-Eleven
{
  "aggregator": "conekta",
  "reference_number": "7ELEV-123456789",
  "barcode": "...",
  "store_name": "7-Eleven",
  "aggregator_order_id": "ord_..."
}
```

---

## 8. Integracion Conekta (Ejemplo)

```typescript
async create7ElevenPayment(userId: string, packageId: string) {
  const pkg = await this.packagesService.findOne(packageId);
  const user = await this.usersService.findOne(userId);

  // Crear orden local
  const order = await this.ordersService.create({
    userId,
    packageId,
    amountMxn: pkg.priceMxn,
    creditsAmount: pkg.currentCredits,
    paymentMethod: 'SEVEN_ELEVEN',
    status: 'CREATED',
    expiresAt: addHours(new Date(), 48)
  });

  // Crear orden en Conekta
  const conektaOrder = await conekta.Order.create({
    currency: 'MXN',
    customer_info: {
      name: user.name,
      email: user.email,
      phone: user.phone
    },
    line_items: [{
      name: `Paquete ${pkg.name}`,
      unit_price: Math.round(pkg.priceMxn * 100),
      quantity: 1
    }],
    charges: [{
      payment_method: {
        type: 'cash',
        expires_at: Math.floor(order.expiresAt.getTime() / 1000)
      }
    }],
    metadata: {
      orderId: order.id,
      userId
    }
  });

  const cashPayment = conektaOrder.charges.data[0].payment_method;

  await this.ordersService.update(order.id, {
    status: 'PENDING',
    metadata: {
      aggregator: 'conekta',
      aggregatorOrderId: conektaOrder.id,
      reference: cashPayment.reference,
      barcode: cashPayment.barcode_url,
      storeName: '7-Eleven'
    }
  });

  return {
    orderId: order.id,
    voucher: {
      reference: cashPayment.reference,
      amount: pkg.priceMxn,
      barcodeUrl: cashPayment.barcode_url,
      expiresAt: order.expiresAt
    }
  };
}
```

---

## 9. Endpoints API

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | /payments/7eleven/create | Crear referencia | JWT |
| GET | /payments/7eleven/:orderId/voucher | Obtener voucher | JWT |
| POST | /payments/webhook/conekta | Webhook Conekta | Sig |

---

## 10. Pantallas Mobile

Reutiliza las pantallas de OXXO con branding 7-Eleven:

| Pantalla | Adaptacion |
|----------|------------|
| **VoucherScreen** | Logo 7-Eleven, colores verde/naranja |
| **PendingPaymentsScreen** | Badge de tienda (OXXO o 7-Eleven) |

---

## 11. UI de Voucher

```
┌─────────────────────────────────────────┐
│          PAGO EN 7-ELEVEN               │
├─────────────────────────────────────────┤
│                                         │
│  🏪 Presenta este codigo en             │
│     cualquier 7-Eleven                  │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │                                 │   │
│  │  ||||| |||| ||||| |||| |||||   │   │
│  │     [CODIGO DE BARRAS]          │   │
│  │                                 │   │
│  │     7ELEV-1234-5678-9012        │   │
│  │                                 │   │
│  └─────────────────────────────────┘   │
│                                         │
│  REFERENCIA: 7ELEV-1234-5678-9012       │
│  MONTO: $100.00 MXN                     │
│  EXPIRA: ⏱️ 47:30:15                    │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │      📤 COMPARTIR VOUCHER       │   │
│  └─────────────────────────────────┘   │
│                                         │
└─────────────────────────────────────────┘
```

---

## 12. Dependencias

### Entrada (Requiere)
- MII-009: Wallet y Creditos
- MII-010: Paquetes de Recarga
- MII-012: Pagos OXXO (patron similar)

### Salida (Bloquea)
- Ninguna directa

---

## 13. Consideraciones

- Evaluar si el volumen justifica integracion adicional
- Conekta cobra por transaccion (evaluar costos)
- Podria implementarse post-MVP si OXXO cubre mayoria
- Mantener UX consistente con OXXO

---

## 14. Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Agregador costoso | Media | Medio | Evaluar ROI, negociar |
| Integracion compleja | Media | Medio | Documentacion, sandbox |
| Poco uso | Media | Bajo | Medir antes de invertir |

---

## 15. Referencias

- [REQUERIMIENTOS-FUNCIONALES.md](../00-vision-general/REQUERIMIENTOS-FUNCIONALES.md) - Seccion 5.11
- [INT-003](../02-integraciones/INT-003-7eleven.md) - Integracion 7-Eleven
- [MII-012](./MII-012-pagos-oxxo.md) - Patron de OXXO

---

**Ultima Actualizacion:** 2026-01-10