miinventario-v2/docs/01-epicas/MII-013-pagos-7eleven.md

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

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

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

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:

-- 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)

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 - Seccion 5.11
• INT-003 - Integracion 7-Eleven
• MII-012 - Patron de OXXO

---

Ultima Actualizacion: 2026-01-10