Descripción general: OAuth REST moderno de PayPal frente a firmas API NVP heredadas
Al integrar PayPal en Passinstance para monetizar pases digitales, entradas de eventos o tarjetas de membresía mediante PassFlow, muchos comercios preguntan cómo solicitar una "firma API de PayPal" (PayPal API Signature).
En el ecosistema histórico de PayPal, la clásica API NVP/SOAP (Name-Value Pair) utilizaba un conjunto de tres credenciales formado por API Username, API Password y API Signature. Sin embargo, los sistemas modernos de comercio electrónico, las aplicaciones de monederos móviles y Passinstance utilizan la API REST v2 de PayPal basada en OAuth 2.0:
| Modelo de credenciales | Arquitectura | Componentes | Compatibilidad y seguridad en la plataforma |
|---|---|---|---|
| API REST moderna de PayPal (Obligatoria) | Credenciales de cliente OAuth 2.0 | Client ID y Client Secret | Compatible: Se tokeniza de forma segura a nivel de espacio de trabajo y admite Smart Payment Buttons, Venmo, Pay in 4 y webhooks en tiempo real. |
| API heredada NVP / SOAP de PayPal | Autenticación clásica de 3 tokens | API Username, API Password, API Signature | Obsoleta: Las escrituras directas de credenciales a nivel de formulario están bloqueadas por rejectLegacySecretWrites en la API de Passinstance. |
Por qué se bloquean las escrituras de secretos heredados (rejectLegacySecretWrites)
En arquitecturas web anteriores, los desarrolladores a veces pegaban contraseñas y firmas API de PayPal directamente en las definiciones de campos de formulario o en la configuración de plantillas. En Passinstance, esa práctica se rechaza de forma estricta:
Importante: En
forms.service.ts(línea 1269), el backend de Passinstance aplicarejectLegacySecretWrites. Cualquier intento de guardar secretos de pago sin cifrar (payPalApiUsername,payPalApiPasswordopayPalApiSignature) dentro de definiciones de formularios públicos o metadatos de plantillas lanza inmediatamente unaBadRequestException.
Las credenciales de pago deben configurarse una sola vez a nivel de espacio de trabajo usando credenciales OAuth REST (Client ID y Client Secret), donde quedan cifradas en el almacén de secretos del inquilino y desacopladas de los formularios públicos de registro.
Guía paso a paso: obtener credenciales REST de PayPal
Siga estos pasos para generar sus credenciales de la API REST de PayPal desde el portal oficial de desarrolladores de PayPal:
Paso 1: inicie sesión en el Portal de Desarrolladores de PayPal
-
1
Abra developer.paypal.com en su navegador.
-
2
Haga clic en Log In to Dashboard en la esquina superior derecha y autentíquese con su cuenta PayPal Business.
Paso 2: abra "Apps & Credentials"
-
1
En el menú de navegación izquierdo, haga clic en Apps & Credentials.
-
2
Seleccione su entorno:
- Sandbox: Utilice credenciales de Sandbox mientras prueba su flujo de pases y diseña plantillas. - Live: Utilice credenciales de Live cuando esté listo para cobrar pagos reales de clientes.
Paso 3: cree una nueva aplicación de API REST
-
1
Haga clic en el botón Create App.
-
2
En el campo App Name, introduzca un nombre identificable (por ejemplo,
Passinstance Wallet Payments). -
3
Establezca App Type en Merchant.
-
4
Si tiene varias cuentas comerciales de Sandbox, seleccione la cuenta de pruebas correspondiente.
-
5
Haga clic en Create App.
Paso 4: copie Client ID y Client Secret
PayPal abrirá la página de detalles de su aplicación:
-
Copie la cadena Client ID.
-
En Secret, haga clic en Show y copie la cadena Client Secret. Mantenga este secreto confidencial.
Configurar PayPal en su espacio de trabajo de Passinstance
Una vez que disponga de sus credenciales REST, conecte PayPal a su espacio de trabajo:
Desde el panel de control:
-
1
Vaya a Configuración -> Integraciones -> Pagos (
/settings/integrations/payments). -
2
Localice PayPal y haga clic en Conectar.
-
3
Seleccione su entorno (Sandbox o Live).
-
4
Pegue su Client ID y su Client Secret.
-
5
Seleccione su divisa predeterminada (por ejemplo,
EUR,USD,GBP). -
6
Haga clic en Guardar y probar conexión. Passinstance realiza un intercambio OAuth automatizado para validar las credenciales antes de activar la pasarela.
Mediante API REST (POST /payments/admin/:customerId/integrations):
POST /api/v1/payments/admin/{customerId}/integrations HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>
Content-Type: application/json
{
"provider": "PAYPAL",
"clientId": "AWr_7B8c9D0e1F2G3H4I5J6K7L8M9N0O1P2Q3R4S5T6U7V8W9X0Y1Z2",
"clientSecret": "EPa_1B2c3D4e5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6",
"mode": "live",
"currency": "EUR"
}
Respuesta (201 Created):
{
"success": true,
"data": {
"provider": "PAYPAL",
"mode": "live",
"currency": "EUR",
"status": "ACTIVE",
"webhookUrl": "https://api.passinstance.com/api/v1/payments/webhooks/paypal"
},
"description": "PayPal integration configured successfully",
"statusCode": 201
}
Configurar el webhook de PayPal para la emisión instantánea de pases
Para emitir pases inmediatamente tras la captura del pago, registre el endpoint de webhook de Passinstance en su Portal de Desarrolladores de PayPal:
-
1
En la página de su aplicación en PayPal dentro de Apps & Credentials, desplácese hasta Webhooks.
-
2
Haga clic en Add Webhook.
-
3
En el campo Webhook URL, introduzca el endpoint de webhook de su espacio de trabajo:
https://api.passinstance.com/api/v1/payments/webhooks/paypal
-
4
En Event Types, marque los siguientes eventos:
- Checkout order approved (CHECKOUT.ORDER.APPROVED) - Payment capture completed (PAYMENT.CAPTURE.COMPLETED) - Payment capture refunded (PAYMENT.CAPTURE.REFUNDED)
-
5
Haga clic en Save. Copie el Webhook ID generado y péguelo en Passinstance dentro de la configuración de su integración con PayPal.
Cuando un cliente autoriza el pago en PassFlow, PayPal notifica a Passinstance mediante este webhook. Passinstance verifica la cabecera criptográfica PAYPAL-TRANSMISSION-SIG, emite el registro del pase y entrega el pase al monedero del cliente.
Resolución de errores frecuentes de PayPal
| Código / Mensaje de error | Causa raíz | Solución |
|---|---|---|
INVALID_CLIENT | El Client ID o Secret es incorrecto, o se usaron credenciales de Sandbox en modo Live. | Compruebe que copió las credenciales con exactitud y que el modo de entorno (Sandbox frente a Live) coincide en ambos sistemas. |
AUTHENTICATION_FAILURE | El Client Secret se restableció en PayPal o contiene espacios al principio o al final. | Genere un nuevo Client Secret en el Panel de Desarrolladores de PayPal y guárdelo de nuevo en Passinstance. |
CURRENCY_NOT_SUPPORTED | La divisa especificada en PassFlow (por ejemplo, JPY o BRL) no está habilitada en su cuenta comercial de PayPal. | Inicie sesión en su cuenta PayPal Business -> Configuración de la cuenta -> Divisas y habilite la divisa deseada. |
| El pase no se emite tras el pago | Falta el webhook de PayPal o está bloqueado por un cortafuegos. | Verifique que la URL del webhook esté guardada en PayPal con el evento PAYMENT.CAPTURE.COMPLETED habilitado. Revise Actividad y registros en Passinstance para consultar las marcas temporales de entrega del webhook. |
Documentación relacionada
-
Venta de pases — Guía completa para configurar pases y entradas de pago en PassFlow.
-
Venta de suscripciones — Gestión de membresías recurrentes con PayPal Subscriptions.
-
Métodos de pago — Gestión de métodos de pago de facturación del espacio de trabajo.
