# INT-002: Integracion Stripe OXXO

---
id: INT-002
type: Integration
status: Pendiente
version: "1.0.0"
created_date: 2026-01-10
updated_date: 2026-01-10
simco_version: "4.0.0"
---

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | INT-002 |
| **Servicio** | Stripe OXXO |
| **Proposito** | Pagos en efectivo en tiendas OXXO |
| **Criticidad** | P0 |
| **Estado** | Pendiente |

---

## 1. Descripcion

Integracion con Stripe para generar vouchers de pago en OXXO, permitiendo a usuarios sin tarjeta comprar creditos pagando en efectivo.

---

## 2. Informacion del Servicio

| Campo | Valor |
|-------|-------|
| Proveedor | Stripe (OXXO) |
| Documentacion | https://stripe.com/docs/payments/oxxo |
| Disponibilidad | Solo Mexico |
| Moneda | MXN |

---

## 3. Configuracion

### Variables de Entorno

```env
# Mismas que INT-001 (Stripe)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
OXXO_EXPIRATION_HOURS=72
```

---

## 4. Flujo de Integracion

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Mobile  │───▶│ Backend  │───▶│  Stripe  │───▶│   OXXO   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │               │               │               │
     │ 1. Request    │               │               │
     │   OXXO pay    │               │               │
     │──────────────▶│               │               │
     │               │ 2. Create PI  │               │
     │               │   type: oxxo  │               │
     │               │──────────────▶│               │
     │               │◀──────────────│               │
     │◀──────────────│   Voucher     │               │
     │               │               │               │
     │ 3. Show       │               │               │
     │   voucher     │               │               │
     │               │               │               │
     │  4. User pays │               │               │
     │   at OXXO     │───────────────────────────────▶
     │               │               │◀──────────────│
     │               │ 5. Webhook    │               │
     │               │◀──────────────│               │
     │◀──────────────│ 6. Notify     │               │
```

---

## 5. Implementacion Backend

### Crear Voucher OXXO

```typescript
async createOxxoPayment(
  amount: number,
  email: string,
  name: string,
  orderId: string
) {
  // Crear PaymentIntent con OXXO
  const paymentIntent = await this.stripe.paymentIntents.create({
    amount: Math.round(amount * 100),
    currency: 'mxn',
    payment_method_types: ['oxxo'],
    payment_method_data: {
      type: 'oxxo',
      billing_details: {
        name: name || 'Usuario MiInventario',
        email: email,
      },
    },
    metadata: {
      orderId,
    },
  });

  // Confirmar para generar voucher
  const confirmed = await this.stripe.paymentIntents.confirm(
    paymentIntent.id
  );

  // Extraer datos del voucher
  const oxxoDetails = confirmed.next_action?.oxxo_display_details;

  return {
    paymentIntentId: paymentIntent.id,
    voucher: {
      number: oxxoDetails.number,
      expiresAt: new Date(oxxoDetails.expires_after * 1000),
      hostedVoucherUrl: oxxoDetails.hosted_voucher_url,
    },
  };
}
```

### Webhook OXXO

```typescript
async handleOxxoWebhook(paymentIntent: Stripe.PaymentIntent) {
  const orderId = paymentIntent.metadata.orderId;

  if (paymentIntent.status === 'succeeded') {
    // Pago completado en OXXO
    await this.ordersService.complete(orderId);
    await this.creditsService.addCredits(
      paymentIntent.metadata.userId,
      paymentIntent.metadata.credits
    );
    await this.notificationsService.sendPaymentConfirmation(orderId);
  }
}
```

---

## 6. Estructura del Voucher

| Campo | Descripcion |
|-------|-------------|
| number | Referencia de pago (16 digitos) |
| expires_after | Unix timestamp de expiracion |
| hosted_voucher_url | URL del voucher en Stripe |

### Ejemplo de Respuesta

```json
{
  "next_action": {
    "type": "oxxo_display_details",
    "oxxo_display_details": {
      "number": "1234567890123456",
      "expires_after": 1704931200,
      "hosted_voucher_url": "https://payments.stripe.com/oxxo/voucher/..."
    }
  }
}
```

---

## 7. Consideraciones

| Aspecto | Valor |
|---------|-------|
| Monto minimo | $10 MXN |
| Monto maximo | $10,000 MXN |
| Expiracion | 72 horas (configurable) |
| Tiempo confirmacion | 10-30 minutos |
| Comision Stripe | ~3.6% + $3 MXN |

---

## 8. Manejo de Estados

| Estado PaymentIntent | Accion |
|---------------------|--------|
| requires_action | Voucher generado, pendiente pago |
| processing | Pago en proceso |
| succeeded | Pago completado |
| canceled | Voucher expirado/cancelado |

---

## 9. Testing

### Modo Test

En modo test, los pagos OXXO se pueden simular:

```bash
# Simular pago exitoso
stripe payment_intents update pi_xxx \
  --status succeeded
```

---

## 10. Referencias

- [Stripe OXXO Docs](https://stripe.com/docs/payments/oxxo)
- [MII-012](../01-epicas/MII-012-pagos-oxxo.md)
- [ADR-0004](../97-adr/ADR-0004-pagos-efectivo-mexico.md)

---

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