--- title: PayPal description: Conecte PayPal a NexCMP para recargas de saldo: credenciales de app REST, webhooks, pruebas en sandbox y cuentas PayPal guardadas. url: https://nexcmp.com/es/docs/billing/paypal/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # PayPal > **Ubicación en el panel:** Finance › Payment channels › PayPal (`/payments/paypal`). El interruptor de activación y las comisiones están en Finance › Payment channels › Fees & limits (`/payments/fees`). ## Qué hace {#what-it-does} Permite a los clientes recargar su monedero en USD con su saldo de PayPal, cuenta bancaria o tarjeta vinculada a PayPal. Los clientes también pueden permitir que NexCMP recuerde su cuenta de PayPal para [recargas automáticas](https://nexcmp.com/es/docs/billing/auto-top-up/). Utilícelo junto con [Stripe](https://nexcmp.com/es/docs/billing/stripe/) para aquellos clientes que prefieran PayPal. ## Requisitos {#requirements} | Elemento | Requisito | |---|---| | Cuenta de PayPal | Una cuenta PayPal **Business** que pueda recibir USD. | | App REST | Una app REST en el PayPal Developer Dashboard (**Apps & Credentials**) que proporcione un **Client ID** y un **Client secret**. Utilice la pestaña **Sandbox** para pruebas y **Live** para producción. | | Red | HTTPS accesible desde Internet (PayPal invoca el webhook) y acceso saliente a `api-m.paypal.com` (live) o `api-m.sandbox.paypal.com` (sandbox), puerto 443. | | Permisos | La app REST necesita los permisos de reembolsos y webhooks. El cuadro de diálogo **Check** muestra si ambos ámbitos están presentes. | | Dependencias | Ninguno. | ## Preparar la infraestructura {#prepare-the-infrastructure} 1. Inicie sesión en [developer.paypal.com](https://developer.paypal.com) con su cuenta Business y abra **Apps & Credentials**. 2. Seleccione **Sandbox** (pruebas) o **Live** y luego haga clic en **Create App**. Asígnele un nombre como, por ejemplo, "NexCMP". 3. Copie el **Client ID** y el **Secret** de la app. 4. Para realizar pruebas, utilice **Testing Tools › Sandbox Accounts** para buscar o crear una cuenta de sandbox *Personal* (comprador). 5. No es necesario que cree el webhook usted mismo; NexCMP lo crea con el botón **Create webhook**. ## Conectar en NexCMP {#connect-in-nexcmp} 1. Abra **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. En **API keys**, elija **Mode**: `live` (dinero real, `api-m.paypal.com`) o `sandbox` (`api-m.sandbox.paypal.com`). 3. Pegue el **Client ID** (al menos 20 caracteres) y el **Client secret**. 4. Haga clic en **Check**. Comprueba las credenciales introducidas (no es necesario guardar) e informa sobre la conexión, el App ID, el modo, si los permisos de reembolso y webhooks están presentes y la duración del token. 5. Haga clic en **Save**. 6. En la tarjeta **Webhook**, confirme que la URL sea `https:///v1/billing/paypal/webhook` (debe ser `https`), luego haga clic en **Create webhook** y confirme. NexCMP solicita a PayPal crear o actualizar el webhook con 11 eventos y almacena el **Webhook ID** devuelto. El botón utiliza las claves **guardadas** — guarde primero si acaba de editarlas. 7. Haga clic en **Check** de nuevo: la fila **Webhook** debe indicar "exists, 11 events". 8. Abra **Fees & limits**, active **PayPal**, configure **PayPal fee %** (predeterminado 4.4) y **PayPal fixed fee (cents)** (predeterminado 30) según su tarifa y haga clic en **Save channels & fees**. ![Página de PayPal con el modo sandbox y credenciales de ejemplo introducidas](https://nexcmp.com/es/docs/images/billing/paypal-01-keys.webp) ### Eventos de webhook {#webhook-events} NexCMP registra estos 11 eventos: `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.PENDING`, `PAYMENT.CAPTURE.DECLINED`, `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`, `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`, `RISK.DISPUTE.CREATED`, `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. Cada webhook se verifica llamando a la API de verificación de firma de PayPal, se almacena una vez y se procesa de forma idempotente. NexCMP nunca confía en el importe del cuerpo del webhook: antes de acreditar una captura, la consulta directamente en PayPal. ## Verificación {#verify} 1. Mantenga **Mode** en `sandbox`. En el portal, abra **Billing › Deposit**, elija **PayPal**, haga clic en **Continue on PayPal** (o en el botón de PayPal) e inicie sesión con la cuenta de comprador de sandbox. 2. Apruebe el pago. Regresará al portal, el saldo aumentará y el pago aparecerá en **Finance › Billing › Top-ups** como *Completed*. 3. Abra **Payment channels › Gateway events › PayPal & USDT**: el evento `PAYMENT.CAPTURE.COMPLETED` aparecerá listado. 4. Cuando todo funcione, cambie **Mode** a `live`, introduzca las credenciales reales, haga clic en **Save** y luego en **Create webhook** de nuevo (los webhooks de sandbox y producción son independientes). ## Límites y notas {#limits-notes} - **Cómo se completa un pago.** La orden se crea en USD; una vez que el cliente la aprueba, el **servidor** la captura (con un ID de solicitud idempotente) y acredita el saldo exactamente una vez. El webhook y una tarea de conciliación que se ejecuta cada 10 minutos actúan como red de seguridad si el cliente cierra el navegador. - **Órdenes pendientes y abandonadas.** Una orden puede permanecer abierta durante 12 horas. Un cliente puede tener como máximo 5 órdenes pendientes (el servidor responde `too_many_pending`, HTTP 429). Una orden que siga sin capturarse tras 24 horas se marca como fallida. - **Sin webhook configurado.** El panel responde HTTP 503 a cada webhook de PayPal hasta que se guarde un Webhook ID. Las capturas realizadas a través del portal y la conciliación cada 10 minutos siguen acreditando el saldo, pero nada de lo que PayPal notifique por webhook (disputas, reversiones, capturas tardías) se aplicará — haga clic en **Create webhook**. - **Cuenta de PayPal guardada.** Cuando el cliente elige guardar PayPal (o completa el primer depósito, lo que activa [automatic top-up](https://nexcmp.com/es/docs/billing/auto-top-up/)), PayPal almacena el token de pago en su bóveda. NexCMP solo conserva un identificador y el correo electrónico de PayPal. Consulte [Saved payment methods](https://nexcmp.com/es/docs/billing/saved-payment-methods/). - **Los reembolsos y las disputas** se gestionan como en Stripe: las solicitudes de reembolso se aprueban en **Finance › Payouts › Card refunds**; una disputa bloquea la cuenta del cliente y suspende sus servicios prepago hasta que usted la resuelva. - **Comisiones.** La comisión de PayPal no se consulta automáticamente; el porcentaje y la comisión fija que configure determinan lo que ve el cliente y lo que se le acredita. La tarifa real depende de su país (el formulario sugiere un 4.4 % para Vietnam y un 3.49 % para EE. UU.). ## Resolución de problemas {#troubleshooting} | Síntoma | Causa | Solución | |---|---|---| | "Client ID demasiado corto" | Se pegaron menos de 20 caracteres | Copie el Client ID completo. | | "La URL del webhook debe ser https" | URL introducida con `http://` | Utilice su dominio público `https://`. | | Check reporta un error de conexión | Modo incorrecto (claves live en sandbox o viceversa), secret erróneo o sin acceso saliente | Haga coincidir **Mode** con el tipo de clave; pruebe `curl -I https://api-m.paypal.com` desde el servidor. | | El scope refund / webhooks muestra "no" | La aplicación REST carece de estas funciones | Habilite las funciones en la aplicación dentro del PayPal Developer Dashboard. | | Banner "Clave de PayPal configurada, SIN webhook" | Falta el Webhook ID | Haga clic en **Create webhook**. | | "Webhook not found" en Check | El webhook se eliminó en PayPal o pertenece a otra aplicación | Haga clic de nuevo en **Create webhook**. | | El cliente recibe el aviso de que PayPal rechazó el pago | PayPal rechazó esa fuente de fondos | Pida al cliente que elija otra fuente de pago. | | El cliente ve "Too many pending requests" | 5 órdenes abiertas | Espere a que caduquen o complételas. | | No aparece el botón de PayPal | PayPal está desactivado en **Fees & limits** o no está configurado | Actívelo y guarde las credenciales. |