# Guía: Pasarelas de Pago en Latinoamérica

> Curso **Crear Páginas Web con Lógica de Negocio** · Módulo 04
> Tabla de decisión + checklist de integración de webhooks. Precios y comisiones son aproximados — verifica siempre en el sitio oficial de cada pasarela.

---

## 1. ¿Qué pasarela para tu país?

| País | Métodos que tu cliente usa | 1ª opción | Alternativa |
|---|---|---|---|
| Colombia | PSE, Nequi, Daviplata, tarjetas, Efecty | **Wompi** | Mercado Pago, PayU |
| México | SPEI, OXXO, tarjetas | **Mercado Pago** | Stripe, Conekta |
| Argentina | Mercado Pago, Rapipago, transferencia | **Mercado Pago** | PayU |
| Perú | Yape, Plin, PagoEfectivo, tarjetas | **Mercado Pago** | Culqi, PayU |
| Chile | Webpay, tarjetas | **Transbank / Mercado Pago** | PayU |
| Brasil | Pix, boleto, tarjetas | **Mercado Pago** | Stripe, PagSeguro |
| Ecuador / Centroamérica | Tarjetas, transferencia, efectivo | **PayU / Kushki** | PagoPlux, local |
| Clientes internacionales (USD) | Tarjetas internacionales | **Stripe** | Paddle, Lemon Squeezy |

## 2. Ficha rápida de las 4 pasarelas del curso

### Wompi (Colombia · de Bancolombia)
- **Métodos:** tarjetas, PSE, Nequi, Botón Bancolombia, efectivo (Corresponsales)
- **Modelo:** sin mensualidad; comisión por transacción (~2,65% + IVA tarjetas; PSE/Nequi tarifa distinta)
- **Sandbox:** completo y sin papeleo; llaves `pub_test_` / secretos de prueba
- **Integración del curso:** checkout redirect + firma de integridad + webhook de eventos

### Mercado Pago (regional · de Mercado Libre)
- **Países:** AR, BR, MX, CL, CO, PE, UY
- **Métodos:** saldo Mercado Pago, tarjetas, efectivo (OXXO, Rapipago…), Pix en BR
- **Modelo:** comisión por transacción, varía por país y por plazo de liberación del dinero
- **Concepto clave:** "preferencia" de pago (`Preference`) + `external_reference` + `notification_url`

### PayU (regional)
- **Países:** CO, MX, AR, PE, CL, PA + red grande de pagos en efectivo
- **Fuerte en:** cobertura de métodos locales antiguos y efectivo
- **Nota:** APIs más antiguas (firma MD5/SHA en formularios), pero muy estables y documentadas en español

### Stripe (global)
- **Fuerte en:** tarjetas internacionales, suscripciones, facturación, developer experience
- **Límite:** no opera localmente en varios países andinos; en LatAm brilla en MX y BR
- **Úsala si:** cobras en USD a clientes fuera de tu país

## 3. El patrón universal (aplica a las 4)

```
1. Tu servidor crea la transacción → referencia ÚNICA + monto desde la BD
2. Rediriges al checkout de la pasarela (los datos de tarjeta nunca te tocan)
3. La pasarela notifica por WEBHOOK (servidor a servidor, firmado)
4. Tu webhook: verifica firma → idempotencia → valida monto → actualiza estado
5. Tu máquina de estados mueve el pedido/cita según el resultado
```

## 4. Checklist de integración de webhooks

- [ ] La referencia se genera en **tu servidor** y es única (`unique` en la BD)
- [ ] El monto sale de la base de datos — jamás de un campo del formulario
- [ ] La firma del evento se **verifica** antes de procesar (401 si no coincide)
- [ ] El procesamiento es **idempotente**: el mismo evento dos veces no duplica efectos
- [ ] El monto notificado se compara contra el monto esperado
- [ ] Referencias desconocidas: responder 200, registrar en logs, no procesar
- [ ] El endpoint responde 200 rápido (la lógica pesada no bloquea la respuesta)
- [ ] La página de "gracias" solo **muestra** estado; nunca lo **decide**
- [ ] Probado en sandbox: aprobado, rechazado y evento duplicado
- [ ] En producción: URL del webhook actualizada al dominio real (módulo 6)

## 5. Máquina de estados de referencia

| Estado pago | Estado Wompi | Estado Mercado Pago | Qué hace tu negocio |
|---|---|---|---|
| PENDIENTE | PENDING | pending / in_process | Mantiene la reserva bloqueada (con límite de tiempo) |
| APROBADO | APPROVED | approved | Confirma cita/pedido + notificación al cliente |
| RECHAZADO | DECLINED | rejected | Permite reintentar el pago |
| ANULADO | VOIDED | refunded / cancelled | Revierte la confirmación según tu política |
| ERROR | ERROR | — | Registra y alerta al admin |

## 6. Tarjetas de prueba (sandbox)

| Pasarela | Aprobada | Rechazada |
|---|---|---|
| Wompi | 4242 4242 4242 4242 | 4111 1111 1111 1111 (según docs sandbox) |
| Mercado Pago | 5031 7557 3453 0604 (MASTER) | usar titular "OTHE" |
| Stripe | 4242 4242 4242 4242 | 4000 0000 0000 0002 |

> Consulta las tablas oficiales de tarjetas de prueba: cambian y cada pasarela define CVV/fechas propias.

---

**Regla de oro del módulo:** el webhook verificado es la única fuente de verdad de un pago. Todo lo demás es decoración.