rckrdmrd
928eb795e6
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8 - Cambios en backend y frontend Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
151 lines
6.3 KiB
Markdown
151 lines
6.3 KiB
Markdown
---
|
|
id: INT-006
|
|
type: Integration
|
|
title: "Pagos CoDi/SPEI"
|
|
provider: "Banxico/STP"
|
|
status: Mock
|
|
integration_type: "Pagos QR instantáneos"
|
|
created_at: 2026-01-10
|
|
updated_at: 2026-01-10
|
|
simco_version: "3.8.0"
|
|
tags:
|
|
- pagos
|
|
- codi
|
|
- spei
|
|
- qr
|
|
- banxico
|
|
- transferencias
|
|
---
|
|
|
|
# INT-006: Pagos CoDi/SPEI
|
|
|
|
## Metadata
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **Codigo** | INT-006 |
|
|
| **Proveedor** | Banxico/STP |
|
|
| **Tipo** | Pagos QR instantáneos |
|
|
| **Estado** | Mock (en desarrollo) |
|
|
| **Multi-tenant** | Si |
|
|
| **Fecha planeada** | 2026-Q1 |
|
|
| **Owner** | Backend Team |
|
|
|
|
---
|
|
|
|
## 1. Descripcion
|
|
|
|
Integración con el sistema de Cobro Digital (CoDi) de Banxico y transferencias SPEI a través de STP (Sistema de Transferencias y Pagos). Permite a los changarros recibir pagos instantáneos mediante códigos QR, sin comisiones por transacción. CoDi opera sobre la infraestructura de SPEI, garantizando transferencias en tiempo real 24/7.
|
|
|
|
**Casos de uso principales:**
|
|
- Generación de códigos QR para cobro instantáneo
|
|
- Recepción de pagos SPEI sin comisión
|
|
- Notificación en tiempo real de pagos recibidos
|
|
- Conciliación automática de transacciones
|
|
- Generación de comprobantes electrónicos de pago
|
|
|
|
---
|
|
|
|
## 2. Credenciales Requeridas
|
|
|
|
### Variables de Entorno
|
|
|
|
| Variable | Descripcion | Tipo | Obligatorio |
|
|
|----------|-------------|------|-------------|
|
|
| STP_EMPRESA | Identificador de empresa en STP | string | SI |
|
|
| STP_CLAVE_PRIVADA | Llave privada para firmar mensajes | string | SI |
|
|
| STP_CERTIFICADO | Certificado digital .cer | string | SI |
|
|
| STP_CUENTA_CLABE | CLABE de la cuenta receptora | string | SI |
|
|
| STP_WEBHOOK_URL | URL para recibir notificaciones | string | SI |
|
|
| CODI_MERCHANT_ID | ID de comercio registrado en CoDi | string | SI |
|
|
| CODI_API_KEY | Llave de API de CoDi | string | SI |
|
|
|
|
### Ejemplo de .env
|
|
|
|
```env
|
|
# Pagos CoDi/SPEI
|
|
STP_EMPRESA=MICHANGARRITO
|
|
STP_CLAVE_PRIVADA=/path/to/private_key.pem
|
|
STP_CERTIFICADO=/path/to/certificate.cer
|
|
STP_CUENTA_CLABE=646180157000000001
|
|
STP_WEBHOOK_URL=https://api.michangarrito.mx/webhooks/stp
|
|
CODI_MERCHANT_ID=codi_mer_xxxxxxxx
|
|
CODI_API_KEY=codi_key_xxxxxxxx
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Arquitectura
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ MiChangarrito │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
|
│ │ Frontend │───▶│ API Server │───▶│ CoDiService │ │
|
|
│ │ (POS/App) │ │ │ │ │ │
|
|
│ └──────────────┘ └──────────────┘ └────────┬─────────┘ │
|
|
└────────────────────────────────────────────────────┼────────────┘
|
|
│
|
|
┌─────────────────────────┼─────────────┐
|
|
│ ▼ │
|
|
│ ┌──────────────────────────────┐ │
|
|
│ │ STP Gateway │ │
|
|
│ └──────────────┬───────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────────────────┐ │
|
|
│ │ Banxico SPEI / CoDi │ │
|
|
│ │ (Red Interbancaria MX) │ │
|
|
│ └──────────────────────────────┘ │
|
|
│ Sistema Financiero │
|
|
└───────────────────────────────────────┘
|
|
```
|
|
|
|
### Flujo de Pago CoDi
|
|
|
|
1. Comercio genera solicitud de cobro con monto
|
|
2. Sistema genera código QR con datos CoDi
|
|
3. Cliente escanea QR con app bancaria
|
|
4. Banco del cliente procesa transferencia SPEI
|
|
5. STP notifica la recepción del pago
|
|
6. Sistema actualiza estado de la venta en tiempo real
|
|
|
|
---
|
|
|
|
## 4. Endpoints
|
|
|
|
### Endpoints Consumidos (STP/CoDi API)
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | `/v1/codi/cobros` | Generar solicitud de cobro CoDi |
|
|
| GET | `/v1/codi/cobros/{id}` | Consultar estado de cobro |
|
|
| POST | `/v1/spei/ordenPago` | Registrar orden de pago SPEI |
|
|
| GET | `/v1/spei/consultaOrden/{id}` | Consultar orden SPEI |
|
|
| GET | `/v1/cuentas/{clabe}/movimientos` | Consultar movimientos |
|
|
|
|
### Endpoints Expuestos (MiChangarrito)
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/v1/payments/codi/generate` | Generar QR de cobro |
|
|
| GET | `/api/v1/payments/codi/{id}/status` | Consultar estado |
|
|
| GET | `/api/v1/payments/codi/{id}/qr` | Obtener imagen QR |
|
|
| POST | `/api/v1/webhooks/stp` | Recibir notificaciones STP |
|
|
| GET | `/api/v1/payments/spei/movements` | Listar movimientos |
|
|
|
|
---
|
|
|
|
## 5. Notas de Implementacion
|
|
|
|
- CoDi no cobra comisiones por transacción (beneficio vs tarjetas)
|
|
- Las transferencias SPEI son irreversibles una vez confirmadas
|
|
- Implementar timeout de 5 minutos para códigos QR
|
|
- Validar firma digital en todas las notificaciones de STP
|
|
- El registro como participante CoDi requiere trámite con Banxico
|
|
- Generar referencia única por transacción para conciliación
|
|
- Los QR deben cumplir con el estándar EMVCo para CoDi
|
|
- Horario de operación SPEI: 24/7, pero cortes contables a las 17:30
|
|
- Considerar implementar caché de CLABEs validadas
|
|
- Manejar reintentos en caso de falla de comunicación con STP
|