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>
139 lines
5.2 KiB
Markdown
139 lines
5.2 KiB
Markdown
---
|
|
id: INT-005
|
|
type: Integration
|
|
title: "Terminal de pagos Clip"
|
|
provider: "Clip México"
|
|
status: Mock
|
|
integration_type: "Pagos con tarjeta"
|
|
created_at: 2026-01-10
|
|
updated_at: 2026-01-10
|
|
simco_version: "3.8.0"
|
|
tags:
|
|
- pagos
|
|
- tarjeta
|
|
- clip
|
|
- pos
|
|
- fintech
|
|
---
|
|
|
|
# INT-005: Terminal de pagos Clip
|
|
|
|
## Metadata
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **Codigo** | INT-005 |
|
|
| **Proveedor** | Clip México |
|
|
| **Tipo** | Pagos con tarjeta |
|
|
| **Estado** | Mock (pendiente de implementar) |
|
|
| **Multi-tenant** | Si |
|
|
| **Fecha planeada** | 2026-Q1 |
|
|
| **Owner** | Backend Team |
|
|
|
|
---
|
|
|
|
## 1. Descripcion
|
|
|
|
Integración con el sistema de terminales punto de venta (TPV) de Clip México para procesar pagos con tarjeta de crédito y débito. Clip es una de las soluciones de pago más populares en México para pequeños comercios, permitiendo aceptar pagos con tarjeta sin necesidad de una cuenta bancaria empresarial tradicional.
|
|
|
|
**Casos de uso principales:**
|
|
- Cobro presencial con tarjeta de crédito/débito en el changarro
|
|
- Generación de links de pago para cobros a distancia
|
|
- Consulta de historial de transacciones y conciliación
|
|
- Gestión de reembolsos y cancelaciones
|
|
- Reportes de ventas por periodo
|
|
|
|
---
|
|
|
|
## 2. Credenciales Requeridas
|
|
|
|
### Variables de Entorno
|
|
|
|
| Variable | Descripcion | Tipo | Obligatorio |
|
|
|----------|-------------|------|-------------|
|
|
| CLIP_API_KEY | Llave de API proporcionada por Clip | string | SI |
|
|
| CLIP_SECRET_KEY | Llave secreta para firmar requests | string | SI |
|
|
| CLIP_MERCHANT_ID | Identificador único del comercio en Clip | string | SI |
|
|
| CLIP_WEBHOOK_SECRET | Secret para validar webhooks de Clip | string | SI |
|
|
| CLIP_ENVIRONMENT | Ambiente (sandbox/production) | string | SI |
|
|
|
|
### Ejemplo de .env
|
|
|
|
```env
|
|
# Terminal de pagos Clip
|
|
CLIP_API_KEY=clip_api_xxxxxxxxxxxxxxxx
|
|
CLIP_SECRET_KEY=clip_secret_xxxxxxxxxxxxxxxx
|
|
CLIP_MERCHANT_ID=mer_xxxxxxxxxxxxxxxx
|
|
CLIP_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx
|
|
CLIP_ENVIRONMENT=sandbox
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Arquitectura
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ MiChangarrito │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
|
│ │ Frontend │───▶│ API Server │───▶│ ClipService │ │
|
|
│ │ (Ventas) │ │ │ │ │ │
|
|
│ └──────────────┘ └──────────────┘ └────────┬─────────┘ │
|
|
└────────────────────────────────────────────────────┼────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────┐
|
|
│ Clip API │
|
|
│ (México) │
|
|
│ │
|
|
│ - Pagos │
|
|
│ - Reembolsos │
|
|
│ - Consultas │
|
|
└──────────────────┘
|
|
```
|
|
|
|
### Flujo de Pago
|
|
|
|
1. Usuario selecciona "Pagar con tarjeta" en el punto de venta
|
|
2. Backend crea una sesión de pago en Clip API
|
|
3. Se genera un link/QR para completar el pago
|
|
4. Cliente realiza el pago con su tarjeta
|
|
5. Clip envía webhook de confirmación
|
|
6. Backend actualiza estado de la venta
|
|
|
|
---
|
|
|
|
## 4. Endpoints
|
|
|
|
### Endpoints Consumidos (Clip API)
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | `/v1/payments` | Crear un nuevo pago |
|
|
| GET | `/v1/payments/{id}` | Consultar estado de pago |
|
|
| POST | `/v1/payments/{id}/refund` | Procesar reembolso |
|
|
| GET | `/v1/transactions` | Listar transacciones |
|
|
| GET | `/v1/merchants/{id}/balance` | Consultar balance |
|
|
|
|
### Endpoints Expuestos (MiChangarrito)
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/v1/payments/clip/create` | Iniciar pago con Clip |
|
|
| GET | `/api/v1/payments/clip/{id}` | Consultar pago |
|
|
| POST | `/api/v1/payments/clip/{id}/refund` | Solicitar reembolso |
|
|
| POST | `/api/v1/webhooks/clip` | Recibir notificaciones de Clip |
|
|
|
|
---
|
|
|
|
## 5. Notas de Implementacion
|
|
|
|
- La integración requiere cuenta de desarrollador en Clip Portal
|
|
- Clip cobra comisión del 3.6% + IVA por transacción
|
|
- Los fondos se depositan en 24-48 horas hábiles
|
|
- Implementar idempotency keys para evitar cobros duplicados
|
|
- Validar firma HMAC en todos los webhooks recibidos
|
|
- Manejar los estados de pago: pending, approved, declined, refunded
|
|
- Considerar límites de rate limiting de la API (100 req/min)
|
|
- En ambiente sandbox usar tarjetas de prueba proporcionadas por Clip
|