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

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. Utilícelo junto con Stripe para aquellos clientes que prefieran PayPal.

Requisitos

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

1. Inicie sesión en 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

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://<your-domain>/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.

Eventos de webhook

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

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

• 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), 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.
• 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

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.