Skip to content
Guía del Centro de ayuda · Integraciones externas
6 min de lecturaVerificado 2026-11-16

Solicitar una firma de API de PayPal y credenciales REST

Configure la integración de pagos de PayPal para la venta de pases: credenciales OAuth modernas de API REST (Client ID y Secret) frente a firmas heredadas de API NVP.

En esta guía

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 credencialesArquitecturaComponentesCompatibilidad y seguridad en la plataforma
API REST moderna de PayPal (Obligatoria)Credenciales de cliente OAuth 2.0Client ID y Client SecretCompatible: 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 PayPalAutenticación clásica de 3 tokensAPI Username, API Password, API SignatureObsoleta: Las escrituras directas de credenciales a nivel de formulario están bloqueadas por rejectLegacySecretWrites en la API de Passinstance.
FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
INTEGRACIÓN PAYPAL REST OAUTH Y EMISIÓN DE PASES
ETAPA 01 PANEL DE DESARROLLADORES DE PAYPAL (COMERCIO)
1
Cree una app REST en Apps & Credentials (Sandbox o Live)
2
Genere Client ID y Client Secret
ETAPA 02 CAPA DE PASARELA DE PAGOS DEL ESPACIO DE TRABAJO PASSINSTANCE
Cifra las credenciales de forma segura en el registro del inquilino
Valida la conexión API de PayPal mediante intercambio de token OAuth 2.0
Monta los botones PayPal Smart Payment Buttons dentro de PassFlow (PaymentStep)
ETAPA 03 RECEPTOR DE WEBHOOKS DE PAYPAL Y EMISIÓN EN TIEMPO REAL
Webhook: PAYMENT.CAPTURE.COMPLETED / CHECKOUT.ORDER.APPROVED
Verifica la firma criptográfica (PAYPAL-TRANSMISSION-SIG)
Dispara la emisión instantánea del pase y entrega botones Apple/Google Wallet

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 aplica rejectLegacySecretWrites. Cualquier intento de guardar secretos de pago sin cifrar (payPalApiUsername, payPalApiPassword o payPalApiSignature) dentro de definiciones de formularios públicos o metadatos de plantillas lanza inmediatamente una BadRequestException.

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. 1
    Abra developer.paypal.com en su navegador.
  2. 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. 1
    En el menú de navegación izquierdo, haga clic en Apps & Credentials.
  2. 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. 1
    Haga clic en el botón Create App.
  2. 2
    En el campo App Name, introduzca un nombre identificable (por ejemplo, Passinstance Wallet Payments).
  3. 3
    Establezca App Type en Merchant.
  4. 4
    Si tiene varias cuentas comerciales de Sandbox, seleccione la cuenta de pruebas correspondiente.
  5. 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. 1
    Vaya a Configuración -> Integraciones -> Pagos (/settings/integrations/payments).
  2. 2
    Localice PayPal y haga clic en Conectar.
  3. 3
    Seleccione su entorno (Sandbox o Live).
  4. 4
    Pegue su Client ID y su Client Secret.
  5. 5
    Seleccione su divisa predeterminada (por ejemplo, EUR, USD, GBP).
  6. 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):

HTTP
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):

JSON
{
  "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. 1
    En la página de su aplicación en PayPal dentro de Apps & Credentials, desplácese hasta Webhooks.
  2. 2
    Haga clic en Add Webhook.
  3. 3
    En el campo Webhook URL, introduzca el endpoint de webhook de su espacio de trabajo:
TEXT
https://api.passinstance.com/api/v1/payments/webhooks/paypal
  1. 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)

  1. 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 errorCausa raízSolución
INVALID_CLIENTEl 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_FAILUREEl 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_SUPPORTEDLa 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 pagoFalta 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.

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.