michangarrito/docs/02-integraciones/INT-005-clip.md

id	type	title	provider	status	integration_type	created_at	updated_at	simco_version	tags
INT-005	Integration	Terminal de pagos Clip	Clip México	Mock	Pagos con tarjeta	2026-01-10	2026-01-10	3.8.0	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

# 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