---
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