# 💳 Guía: Configurar PayPal Live (producción)

Guía paso a paso para obtener las credenciales **reales** de PayPal (Client ID + Secret)
en `developer.paypal.com` y activar los cobros en TechShop Perú.

> ⚠️ **Antes de empezar**: esta tienda captura pagos **desde el servidor**
> (`api/verify-paypal.php`, Orders v2). No basta con poner un Client ID: sin el
> **Client Secret** correcto, el pedido no se confirma y el cliente ve un error.
> Completa **todos** los pasos antes de anunciar el método de pago.

---

## 1. Crear una app en PayPal Developer

1. Entra a [developer.paypal.com](https://developer.paypal.com) con la cuenta
   de PayPal **dueña de la cuenta de cobros** (la que recibirá el dinero).
2. Menú superior → **Apps & Credentials** (o Dashboard → Apps & Credentials).
3. Si te pide verificar la cuenta, sigue el flujo (número de teléfono / correo).
4. En la pestaña **Live**, pulsa **Create App**.
   - *"Apps & Credentials"* muestra dos entornos: **Sandbox** (pruebas) y **Live** (real).
   - Asegúrate de crear la app en la pestaña **Live** (¡es fácil crearla en Sandbox por error!).
5. Nombre de la app: `TechShop Perú` (o similar) → **Create App**.
6. La pantalla siguiente muestra tu **Client ID** y **Secret** de producción:
   - **Client ID**: se copia al panel (es público, puede ir en el frontend).
   - **Secret**: está oculto (botón **Show** / **Reset**). **Nunca compartirlo**.

> 🔒 **Consejo**: usa el botón **Reset** para regenerar el Secret si sospechas que
> alguien lo vio. El Client ID normalmente no necesita regenerse.

---

## 2. Configurar la app (si aplica)

En la misma pantalla de la app Live:

- **Return URLs** / **Webhooks**: esta tienda usa el flujo del JS SDK + captura
  server-side, por lo que **no requiere** URLs de retorno ni webhooks para funcionar.
  PayPal redirige automáticamente al cliente al completar el pago en la ventana del SDK.
- Si tu plan/API pide un dominio permitido, añade tu dominio de producción
  (ej. `https://tudominio.com`). En la mayoría de las apps nuevas esto no se solicita.

---

## 3. Configurar las credenciales en el panel

1. Ve a `/panel-admin-tech/configuracion.php` (menú **Configuración**).
2. Sección **Configuración de Pagos**:
   - **PayPal Client ID** → pega el Client ID de la app **Live**.
   - **PayPal Client Secret** → pega el Secret (se guarda oculto; dejar vacío = no cambiar).
   - **Modo PayPal** → selecciona **Live (producción)**.
3. Pulsa **Guardar Cambios**.

> El panel carga el botón de PayPal en el checkout solo si `Client ID` no está vacío.
> Con `paypal_mode = live`, las peticiones van a `https://api-m.paypal.com`
> (en sandbox van a `https://api-m.sandbox.paypal.com`).

---

## 4. Verificar las credenciales antes de publicar

Prueba que las credenciales emiten un token de acceso contra la API de PayPal:

```bash
curl -s -u "TU_CLIENT_ID:TU_CLIENT_SECRET" \
  https://api-m.paypal.com/v1/oauth2/token \
  -d "grant_type=client_credentials" | head -c 300
```

- **Respuesta esperada** (empieza así):
  ```json
  {"scope":"https://uri.paypal.com/services/...","access_token":"A21AAJ...","app_id":"APP-...","expires_in":32400,...}
  ```
- Si responde `401 Unauthorized` → las credenciales no son válidas o **no son las de Live**
  (revisa que copiaste las de la pestaña Live, no Sandbox).

> 💡 Para probar el **flujo completo real**, haz un pedido de prueba de S/ 1.00
> en la tienda y paga con tu propia tarjeta PayPal. Luego cancélalo desde el panel
> (el dinero se devuelve a tu cuenta).

---

## 5. Activar la cuenta PayPal para cobros (importante)

Aunque tengas credenciales válidas, la cuenta debe estar habilitada para recibir
pagos comerciales:

1. Entra a [paypal.com](https://www.paypal.com) con la misma cuenta.
2. Completa la **verificación de la cuenta** (cuenta bancaria o tarjeta vinculada).
3. Revisa que el **nombre legal / empresa** sea el que figurará en los cargos.
4. En muchos países (incluido Perú) PayPal exige configuración adicional de
   **moneda**: el checkout cobra en **USD** (la tienda convierte soles a USD con
   la tasa `PAYPAL_USD_RATE`, por defecto 3.75). Asegúrate de que tu cuenta
   pueda recibir USD o el pago se rechazará.

---

## 6. Cambiar a producción (sandbox → live) en la BD

La app arranca en `sandbox` por defecto. Al poner **Live** desde el panel se guarda
`paypal_mode = live`. Verifícalo en la base de datos:

```sql
SELECT clave, valor FROM configuracion WHERE clave IN ('paypal_client_id','paypal_client_secret','paypal_mode');
-- Esperado: paypal_mode = 'live' y los client id/secret llenos
```

> ℹ️ Las claves `paypal_*` y `smtp_*` **no vienen en el dump**: se crean en la
tabla `configuracion` al **guardar por primera vez el formulario del panel**.
Si el `SELECT` no devuelve filas, es normal antes de configurarlas desde el
panel (los valores se guardan al pulsar "Guardar Cambios").

> ℹ️ Nota: en este proyecto el modo PayPal se lee **únicamente** desde la tabla
> `configuracion` (vía `init_db_config()` → constante `PAYPAL_MODE`). El `.env`
> solo alimenta `DB_*` y `APP_ENV`; **no** sirve para forzar `PAYPAL_MODE`.
> **La forma oficial es el panel.**

---

## 7. Checklist final antes del lanzamiento

- [ ] App creada en la pestaña **Live** de Apps & Credentials
- [ ] `Client ID` y `Secret` copiados desde Live (no Sandbox)
- [ ] `paypal_mode = live` en el panel
- [ ] `curl` de verificación devuelve `access_token` (paso 4)
- [ ] Cuenta PayPal verificada y habilitada para recibir USD
- [ ] Pedido real de prueba completado y visible en el panel con estado **confirmado**
- [ ] Pedido de prueba cancelado (reembolso OK)
- [ ] El checkout **no** muestra el botón de PayPal si se borran las credenciales (fallback controlado)

---

## Solución de problemas

| Síntoma | Causa probable | Solución |
|---|---|---|
| `No se pudo autenticar con PayPal` en logs | Secret incorrecto o de Sandbox | Copiar el Secret **Live** (botón Reset si hace falta) |
| `PayPal rechazó la captura (HTTP 401)` | Client ID/Secret no coinciden con `paypal_mode` | Revisar que modo = `live` y credenciales de Live |
| El botón de PayPal no aparece en checkout | `PAYPAL_CLIENT_ID` vacío | Completar Client ID en el panel y guardar |
| El monto confirmado no coincide | Cambió la tasa de cambio real vs `PAYPAL_USD_RATE` | La tasa por defecto es 3.75 y **no tiene campo en el panel**. Para cambiarla, inserta/actualiza la fila en la BD: `INSERT INTO configuracion (clave, valor) VALUES ('paypal_usd_rate', '4.00') ON DUPLICATE KEY UPDATE valor = VALUES(valor);` (se lee en el siguiente checkout) |
| Pago aprobado pero pedido no creado | Falló la verificación server-side | Revisar `error_log`; el cliente NO fue cobrado (captura no confirmada) |

---

*Documento asociado: `README_PRODUCCION.md` (despliegue completo).*
