PayPal

Onde encontrar no admin: Finance › Payment channels › PayPal (/payments/paypal). O botão de ligar/desligar e as taxas ficam em Finance › Payment channels › Fees & limits (/payments/fees).

O que faz

Permite que os clientes recarreguem a carteira em USD com o saldo do PayPal, conta bancária ou cartão vinculado ao PayPal. Os clientes também podem permitir que o NexCMP lembre da conta do PayPal para recargas automáticas. Use junto com Stripe para clientes que preferem o PayPal.

Requisitos

Item	Requisito
PayPal account	Uma conta Business do PayPal que possa receber em USD.
REST app	Um aplicativo REST no Painel de Desenvolvedores do PayPal (Apps & Credentials) que forneça um Client ID e um Client secret. Use a aba Sandbox para testes e Live para produção.
Rede	HTTPS acessível pela Internet (o PayPal aciona o webhook) e acesso de saída para api-m.paypal.com (live) ou api-m.sandbox.paypal.com (sandbox), porta 443.
Permissões	O aplicativo REST precisa dos recursos de reembolso e webhooks. O diálogo Check mostra se ambos os escopos estão presentes.
Dependências	Nenhum.

Preparar a infraestrutura

1. Entre em developer.paypal.com com sua conta Business e abra Apps & Credentials.
2. Escolha Sandbox (testes) ou Live e clique em Create App. Dê um nome a ele, por exemplo, "NexCMP".
3. Copie o Client ID e o Secret do aplicativo.
4. Para testes, use Testing Tools › Sandbox Accounts para localizar ou criar uma conta de sandbox Personal (comprador).
5. Você não precisa criar o webhook por conta própria; o NexCMP o cria com o botão Create webhook.

Conectar no NexCMP

1. Abra Finance › Payment channels › PayPal (/payments/paypal).
2. Em API keys, escolha Mode: live (dinheiro real, api-m.paypal.com) ou sandbox (api-m.sandbox.paypal.com).
3. Cole o Client ID (pelo menos 20 caracteres) e o Client secret.
4. Clique em Check. Isso testa as credenciais digitadas (salvar não é obrigatório) e relata a conexão, o App ID, o modo, se os escopos de reembolso e webhooks estão presentes e por quanto tempo o token dura.
5. Clique em Save.
6. No cartão Webhook, confirme se a URL é https://<your-domain>/v1/billing/paypal/webhook (ela deve ser https), clique em Create webhook e confirme. O NexCMP solicita que o PayPal crie ou atualize o webhook com 11 eventos e armazena o Webhook ID retornado. O botão usa as chaves salvas — salve primeiro caso tenha acabado de editá-las.
7. Clique em Check novamente: a linha Webhook deve exibir "exists, 11 events".
8. Abra Fees & limits, ative PayPal, defina PayPal fee % (padrão 4.4) e PayPal fixed fee (cents) (padrão 30) para a sua tarifa e clique em Save channels & fees.

Eventos de webhook

O NexCMP registra estes 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 é verificado chamando a API de verificação de assinatura do PayPal, armazenado uma única vez e processado de forma idempotente. O NexCMP nunca confia no valor presente no corpo do webhook: antes de creditar uma captura, ele busca a captura diretamente no PayPal.

Verificar

1. Mantenha Mode em sandbox. No portal, abra Billing › Deposit, escolha PayPal, clique em Continue on PayPal (ou no botão do PayPal) e faça login com a conta de comprador de sandbox.
2. Aprove o pagamento. Você retornará ao portal, o saldo aumentará e o pagamento aparecerá em Finance › Billing › Top-ups como Completed.
3. Abra Payment channels › Gateway events › PayPal & USDT: o evento PAYMENT.CAPTURE.COMPLETED estará listado.
4. Quando tudo estiver funcionando, altere Mode para live, insira as credenciais de produção, clique em Save e, em seguida, em Create webhook novamente (os webhooks de sandbox e de produção são separados).

Limites e notas

• Como um pagamento é concluído. O pedido é criado em USD; após o cliente aprová-lo, o server faz a captura (com ID de requisição idempotente) e credita a carteira exatamente uma vez. O webhook e uma rotina de conciliação executada a cada 10 minutos servem como redes de segurança caso o cliente feche o navegador.
• Pedidos pendentes e abandonados. Um pedido pode permanecer aberto por 12 horas. Um cliente pode ter no máximo 5 pedidos pendentes (o servidor responde too_many_pending, HTTP 429). Um pedido que ainda não tenha sido capturado após 24 horas é marcado como falhou.
• Nenhum webhook configurado. O painel responde HTTP 503 a todos os webhooks do PayPal até que um Webhook ID seja salvo. Capturas feitas pelo portal e a conciliação de 10 minutos ainda creditam a carteira, mas nada relatado pelo PayPal via webhook (disputas, estornos, capturas tardias) é aplicado — clique em Create webhook.
• Conta do PayPal salva. Quando o cliente opta por salvar o PayPal (ou conclui o primeiro depósito, o que ativa a recarga automática), o PayPal armazena o token de pagamento em seu cofre. O NexCMP mantém apenas um identificador e o e-mail do PayPal. Consulte Saved payment methods.
• Reembolsos e disputas são tratados da mesma forma que no Stripe: solicitações de reembolso são aprovadas em Finance › Payouts › Card refunds; uma disputa bloqueia a conta do cliente e suspende seus serviços pré-pagos até que você a resolva.
• Taxas. A taxa do PayPal não é lida de volta; a porcentagem e a taxa fixa configuradas determinam o que o cliente vê e o que é creditado. A tarifa real depende do seu país (o formulário sugere 4.4 % para o Vietnã e 3.49 % para os EUA).

Resolução de problemas

Sintoma	Causa	Correção
"Client ID muito curto"	Menos de 20 caracteres colados	Copie o Client ID completo.
"A URL do webhook deve ser https"	URL digitada com http://	Use o seu domínio https:// público.
A verificação relata um erro de conexão	Modo incorreto (chaves de produção em sandbox ou vice-versa), segredo incorreto, sem acesso de saída	Faça corresponder Mode ao tipo de chave; teste curl -I https://api-m.paypal.com a partir do servidor.
Escopo de reembolso / webhooks mostra "no"	O aplicativo REST não possui os recursos	Ative os recursos no aplicativo no Painel de Desenvolvedor do PayPal.
Banner "Chave do PayPal definida, SEM webhook"	ID do webhook ausente	Clique em Create webhook.
"Webhook not found" na Verificação	O webhook foi excluído no PayPal ou pertence a outro aplicativo	Clique em Create webhook novamente.
O cliente recebe a informação de que o PayPal recusou o pagamento	O PayPal rejeitou essa fonte de financiamento	Peça ao cliente para escolher outra fonte de pagamento.
O cliente vê "Too many pending requests"	5 pedidos abertos	Aguarde até que expirem ou conclua-os.
Botão do PayPal ausente	PayPal desativado em Fees & limits ou não configurado	Ative-o e salve as credenciais.