miinventario-v2/docs/02-integraciones/INT-002-oxxo.md

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

# 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

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

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

{
  "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:

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

---

10. Referencias

• Stripe OXXO Docs
• MII-012
• ADR-0004

---

Ultima Actualizacion: 2026-01-10