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 credenciais | Arquitetura | Componentes | Suporte na plataforma e segurança |
|---|---|---|---|
| PayPal REST API Moderna (Obrigatória) | Credenciais de Cliente OAuth 2.0 | Client ID e Client Secret | Suportada: 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 Legada | Autenticação Clássica de 3 Tokens | API Username, API Password, API Signature | Descontinuada: Gravações diretas de credenciais ao nível de formulários são bloqueadas via rejectLegacySecretWrites na API da Passinstance. |
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õerejectLegacySecretWrites. Qualquer tentativa de guardar segredos de pagamento em bruto (payPalApiUsername,payPalApiPasswordoupayPalApiSignature) dentro de definições públicas de formulários ou metadados de modelos gera imediatamente umaBadRequestException.
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
Abra developer.paypal.com no seu navegador.
-
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
No menu de navegação esquerdo, clique em Apps & Credentials.
-
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
Clique no botão Create App.
-
2
No campo App Name, introduza um nome identificável (por exemplo,
Passinstance Wallet Payments). -
3
Defina App Type como Merchant.
-
4
Se tiver várias contas empresariais Sandbox, selecione a conta de teste relevante.
-
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
Aceda a Definições -> Integrações -> Pagamentos (
/settings/integrations/payments). -
2
Localize PayPal e clique em Ligar.
-
3
Selecione o ambiente (Sandbox ou Live).
-
4
Cole o seu Client ID e Client Secret.
-
5
Selecione a sua moeda predefinida (por exemplo,
EUR,USD,GBP). -
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):
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):
{
"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
Na página da sua aplicação PayPal em Apps & Credentials, desloque-se para baixo até Webhooks.
-
2
Clique em Add Webhook.
-
3
No campo Webhook URL, introduza o endpoint de webhook do seu espaço de trabalho:
https://api.passinstance.com/api/v1/payments/webhooks/paypal
-
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)
-
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 erro | Causa raiz | Solução |
|---|---|---|
INVALID_CLIENT | O 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_FAILURE | O 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_SUPPORTED | A 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 pagamento | O 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
-
Vender passes — Guia completo para configurar passes pagos e bilhetes no PassFlow.
-
Vender subscrições — Gerir adesões recorrentes de clubes com PayPal Subscriptions.
-
Métodos de pagamento — Gerir métodos de pagamento da faturação do espaço de trabalho.
