rckrdmrd
1a53b5c4d3
- Backend NestJS con módulos de autenticación, inventario, créditos - Frontend React con dashboard y componentes UI - Base de datos PostgreSQL con migraciones - Tests E2E configurados - Configuración de Docker y deployment Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
222 lines
5.7 KiB
Markdown
222 lines
5.7 KiB
Markdown
# 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
|