--- title: PayPal description: Conecte o PayPal ao NexCMP para recargas de saldo — credenciais de aplicativo REST, webhook, testes em sandbox e contas do PayPal salvas. url: https://nexcmp.com/pt/docs/billing/paypal/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # 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 {#what-it-does} 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](https://nexcmp.com/pt/docs/billing/auto-top-up/). Use junto com [Stripe](https://nexcmp.com/pt/docs/billing/stripe/) para clientes que preferem o PayPal. ## Requisitos {#requirements} | 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 {#prepare-the-infrastructure} 1. Entre em [developer.paypal.com](https://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 {#connect-in-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:///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**. ![Página do PayPal com o modo sandbox e credenciais de exemplo inseridas](https://nexcmp.com/pt/docs/images/billing/paypal-01-keys.webp) ### Eventos de webhook {#webhook-events} 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 {#verify} 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 {#limits-notes} - **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](https://nexcmp.com/pt/docs/billing/auto-top-up/)), 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](https://nexcmp.com/pt/docs/billing/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 {#troubleshooting} | 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. |