Skip to content
Guia da Central de Ajuda · Integrações externas
5 min de leituraVerificado 2026-11-16

Solicitando uma assinatura de API do PayPal e credenciais REST

Configure a integração de pagamento do PayPal para vendas de passes: credenciais OAuth modernas da API REST (Client ID e Secret) versus assinaturas legadas da API NVP.

Neste guia

Visão geral: PayPal REST OAuth moderno vs. assinaturas legadas da API NVP

Ao integrar o PayPal na Passinstance para monetizar passes digitais, bilhetes de eventos ou cartões de sócio através do PassFlow, os comerciantes perguntam frequentemente como solicitar uma "PayPal API Signature".

No ecossistema histórico do PayPal, a API clássica NVP/SOAP (Name-Value Pair) utilizava um conjunto de credenciais em 3 partes composto por API Username, API Password e API Signature. Contudo, os sistemas modernos de comércio eletrónico, aplicações de carteiras móveis e a Passinstance utilizam a PayPal REST API v2 alimentada por OAuth 2.0:

Modelo de credenciaisArquiteturaComponentesSuporte na plataforma e segurança
PayPal REST API Moderna (Obrigatória)Credenciais de Cliente OAuth 2.0Client ID e Client SecretSuportada: Tokenizada com segurança ao nível do espaço de trabalho, suporta Smart Payment Buttons, Venmo, Pay in 4 e webhooks em tempo real.
PayPal NVP / SOAP API LegadaAutenticação Clássica de 3 TokensAPI Username, API Password, API SignatureDescontinuada: Gravações diretas de credenciais ao nível de formulários são bloqueadas via rejectLegacySecretWrites na API da Passinstance.
FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
INTEGRAÇÃO PAYPAL REST OAUTH E EMISSÃO
ETAPA 01 PAINEL DE PROGRAMADOR PAYPAL (COMERCIANTE)
1
Criar Aplicação REST em Apps & Credentials (Sandbox ou Live)
2
Gerar Client ID e Client Secret
ETAPA 02 CAMADA DE GATEWAY DE PAGAMENTOS DO ESPAÇO DE TRABALHO
Encripta credenciais com segurança no registo do tenant
Valida handshake da API PayPal via troca de token OAuth 2.0 Bearer
Monta PayPal Smart Payment Buttons dentro do PassFlow (PaymentStep)
ETAPA 03 RECETOR DE WEBHOOKS PAYPAL E EMISSÃO EM TEMPO REAL
Webhook: PAYMENT.CAPTURE.COMPLETED / CHECKOUT.ORDER.APPROVED
Verifica a assinatura criptográfica (PAYPAL-TRANSMISSION-SIG)
Aciona emissão imediata do passe e apresenta botões Apple/Google Wallet

Porque é que gravações de segredos legados são bloqueadas (rejectLegacySecretWrites)

Em arquiteturas web mais antigas, os programadores colavam por vezes palavras-passe e assinaturas de API do PayPal diretamente em definições de campos de formulários ou definições de modelos. Na Passinstance, esta prática é estritamente rejeitada:

Importante: Em forms.service.ts (linha 1269), o backend da Passinstance impõe rejectLegacySecretWrites. Qualquer tentativa de guardar segredos de pagamento em bruto (payPalApiUsername, payPalApiPassword ou payPalApiSignature) dentro de definições públicas de formulários ou metadados de modelos gera imediatamente uma BadRequestException.

As credenciais de pagamento têm de ser configuradas uma única vez ao nível do espaço de trabalho utilizando credenciais REST OAuth (Client ID e Client Secret), sendo encriptadas no cofre do tenant e desacopladas dos formulários públicos de registo.


Guia passo a passo: Obter credenciais REST do PayPal

Siga estes passos para gerar as suas credenciais PayPal REST API no Portal de Programadores oficial do PayPal:

Passo 1: Iniciar sessão no PayPal Developer Portal

  1. 1
    Abra developer.paypal.com no seu navegador.
  2. 2
    Clique em Log In to Dashboard no canto superior direito e autentique-se com a sua Conta PayPal Business.

Passo 2: Abrir "Apps & Credentials"

  1. 1
    No menu de navegação esquerdo, clique em Apps & Credentials.
  2. 2
    Selecione o seu ambiente:

- Sandbox: Utilize credenciais Sandbox enquanto testa o fluxo de passes e concebe modelos. - Live: Utilize credenciais Live quando estiver pronto para cobrar pagamentos reais aos clientes.

Passo 3: Criar uma nova aplicação REST API

  1. 1
    Clique no botão Create App.
  2. 2
    No campo App Name, introduza um nome identificável (por exemplo, Passinstance Wallet Payments).
  3. 3
    Defina App Type como Merchant.
  4. 4
    Se tiver várias contas empresariais Sandbox, selecione a conta de teste relevante.
  5. 5
    Clique em Create App.

Passo 4: Copiar Client ID e Client Secret

O PayPal abre a página de detalhes da sua aplicação:

  • Copie a string Client ID.
  • Em Secret, clique em Show e copie a string Client Secret. Mantenha este segredo confidencial.

Configurar o PayPal no seu espaço de trabalho Passinstance

Assim que tiver as suas credenciais REST, ligue o PayPal ao seu espaço de trabalho:

Através do Painel:

  1. 1
    Aceda a Definições -> Integrações -> Pagamentos (/settings/integrations/payments).
  2. 2
    Localize PayPal e clique em Ligar.
  3. 3
    Selecione o ambiente (Sandbox ou Live).
  4. 4
    Cole o seu Client ID e Client Secret.
  5. 5
    Selecione a sua moeda predefinida (por exemplo, EUR, USD, GBP).
  6. 6
    Clique em Guardar e Testar Ligação. A Passinstance realiza um handshake OAuth automatizado para confirmar as credenciais antes de ativar a gateway.

Através da 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"
}

Resposta (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 o webhook PayPal para emissão imediata de passes

Para emitir passes imediatamente após a captura do pagamento, registe o endpoint de webhook da Passinstance no seu PayPal Developer Portal:

  1. 1
    Na página da sua aplicação PayPal em Apps & Credentials, desloque-se para baixo até Webhooks.
  2. 2
    Clique em Add Webhook.
  3. 3
    No campo Webhook URL, introduza o endpoint de webhook do seu espaço de trabalho:
TEXT
https://api.passinstance.com/api/v1/payments/webhooks/paypal
  1. 4
    Em Event Types, selecione os seguintes eventos:

- Checkout order approved (CHECKOUT.ORDER.APPROVED) - Payment capture completed (PAYMENT.CAPTURE.COMPLETED) - Payment capture refunded (PAYMENT.CAPTURE.REFUNDED)

  1. 5
    Clique em Save. Copie o Webhook ID gerado e cole-o na Passinstance, nas definições da sua integração PayPal.

Quando um cliente autoriza o pagamento no PassFlow, o PayPal notifica a Passinstance através deste webhook. A Passinstance verifica o cabeçalho criptográfico PAYPAL-TRANSMISSION-SIG, emite o registo do passe e entrega o passe à carteira do cliente.


Resolução de erros comuns do PayPal

Código / Mensagem de erroCausa raizSolução
INVALID_CLIENTO Client ID ou o Secret está incorreto, ou foram usadas credenciais Sandbox em modo Live.Verifique se copiou corretamente as credenciais e se o modo de ambiente (Sandbox vs. Live) coincide em ambos os sistemas.
AUTHENTICATION_FAILUREO Client Secret foi redefinido no PayPal ou contém espaços no início/fim.Gere um novo Client Secret no Painel de Programador PayPal e volte a guardá-lo na Passinstance.
CURRENCY_NOT_SUPPORTEDA moeda especificada no PassFlow (por exemplo, JPY ou BRL) não está ativada na sua conta comercial PayPal.Inicie sessão na sua Conta PayPal Business -> Definições da Conta -> Moedas e ative a moeda pretendida.
Passe não emitido após pagamentoO webhook do PayPal está em falta ou bloqueado por firewall.Verifique se o URL do webhook está guardado no PayPal com o evento PAYMENT.CAPTURE.COMPLETED ativado. Consulte Atividade e Registos na Passinstance para verificar os carimbos temporais de entrega dos webhooks.

Documentação relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.