---
id: INT-004
type: Integration
title: "Mercado Pago"
provider: "MercadoPago"
status: Pendiente
integration_type: "payments"
created_at: 2026-01-04
updated_at: 2026-01-10
simco_version: "3.8.0"
tags:
  - mercadopago
  - payments
  - point-of-sale
  - multi-tenant
---

# INT-004: Mercado Pago

## Metadata

| Campo | Valor |
|-------|-------|
| **Codigo** | INT-004 |
| **Proveedor** | Mercado Libre |
| **Tipo** | Terminal de Pago |
| **Estado** | Pendiente |
| **Multi-tenant** | Si (por tenant) |
| **Fecha integracion** | - |
| **Ultimo update** | 2026-01-10 |
| **Owner** | Backend Team |

---

## 1. Descripcion

Mercado Pago es una opcion de terminal de pago fisica para que los duenos de tiendas puedan aceptar pagos con tarjeta. A diferencia de Stripe (que maneja suscripciones), MercadoPago se usa para cobros en punto de venta.

**Casos de uso principales:**
- Cobro con tarjeta en tienda fisica
- QR para cobro
- Generacion de links de pago
- Integracion con terminal Point

---

## 2. Credenciales Requeridas

### Variables de Entorno

| Variable | Descripcion | Tipo | Obligatorio |
|----------|-------------|------|-------------|
| `MERCADOPAGO_ACCESS_TOKEN` | Access Token de la aplicacion | string | SI |
| `MERCADOPAGO_PUBLIC_KEY` | Public Key para frontend | string | SI |
| `MERCADOPAGO_WEBHOOK_SECRET` | Secret para webhooks (IPN) | string | SI |

### Ejemplo de .env

```env
# Mercado Pago
MERCADOPAGO_ACCESS_TOKEN=APP_USR-xxxxxxxx
MERCADOPAGO_PUBLIC_KEY=APP_USR-xxxxxxxx
MERCADOPAGO_WEBHOOK_SECRET=xxxxxxxx
```

### Obtencion de Credenciales

1. Crear cuenta en [Mercado Pago Developers](https://www.mercadopago.com.mx/developers/)
2. Crear aplicacion
3. Obtener credenciales de produccion
4. Configurar URL de IPN (webhook)

---

## 3. Endpoints/SDK Utilizados

### Operaciones Planificadas

| Operacion | SDK Method | Descripcion |
|-----------|------------|-------------|
| Crear Preferencia | `preference.create()` | Link de pago |
| Crear QR | `qr.create()` | Cobro por QR |
| Consultar Pago | `payment.get()` | Estado del pago |

### SDK Planificado

```typescript
import { MercadoPagoConfig, Preference, Payment } from 'mercadopago';

const client = new MercadoPagoConfig({
  accessToken: process.env.MERCADOPAGO_ACCESS_TOKEN,
});

const preference = new Preference(client);

// Crear link de pago
const result = await preference.create({
  body: {
    items: [{
      title: 'Venta en tienda',
      unit_price: 100,
      quantity: 1,
    }],
    back_urls: {
      success: 'https://michangarrito.com/pago/exitoso',
      failure: 'https://michangarrito.com/pago/fallido',
    },
  },
});
```

---

## 4. Rate Limits

| Limite | Valor | Periodo | Accion si excede |
|--------|-------|---------|------------------|
| API calls | 10,000 | por minuto | 429 |

---

## 5. Manejo de Errores

### Codigos de Error (Planeados)

| Codigo | Descripcion | Accion Recomendada |
|--------|-------------|-------------------|
| 400 | Parametros invalidos | Validar input |
| 401 | Token invalido | Verificar credenciales |
| 404 | Recurso no encontrado | Verificar ID |

---

## 6. Multi-tenant

### Modelo de Credenciales

- [x] **Por Tenant:** Cada tenant usa su cuenta MercadoPago

Los fondos van directo a la cuenta del dueno de la tienda.

### Almacenamiento Planificado

```sql
CREATE TABLE sales.tenant_mercadopago_config (
    id UUID PRIMARY KEY,
    tenant_id UUID REFERENCES auth.tenants(id),
    access_token TEXT NOT NULL, -- Encriptado
    public_key VARCHAR(100),
    collector_id VARCHAR(50),
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(tenant_id)
);
```

---

## 7. Webhooks (IPN)

### Endpoints Planificados

| Evento | Endpoint Local | Descripcion |
|--------|----------------|-------------|
| `payment` | `/webhooks/mercadopago` | Pago recibido |
| `merchant_order` | `/webhooks/mercadopago` | Orden actualizada |

---

## 8. Estado de Implementacion

### Checklist

- [ ] Crear modulo MercadoPago en backend
- [ ] Implementar servicio de pagos
- [ ] Configurar webhooks
- [ ] Integrar con flujo de ventas
- [ ] Testing en sandbox
- [ ] Documentar flujo completo

### Bloqueadores

- Requiere onboarding de tenants a MercadoPago
- Proceso de verificacion de cuenta

---

## 9. Referencias

### Documentacion Oficial
- [MercadoPago Developers](https://www.mercadopago.com.mx/developers/es)
- [API Reference](https://www.mercadopago.com.mx/developers/es/reference)
- [SDK Node.js](https://github.com/mercadopago/sdk-nodejs)

---

**Ultima actualizacion:** 2026-01-10
**Estado:** PENDIENTE DE IMPLEMENTACION