PayPal

O que você precisa

Por que pedimos cada campo

Client ID

Identifica o seu app PayPal nas chamadas de API. Funciona apenas quando pareado com o Client secret.

Client secret

A metade privada da autenticação de API. Com o Client ID, permite criarmos o pedido, para que o pagamento corra pela sua conta.

Webhook ID

Como confirmamos que um webhook é genuinamente do PayPal: o PayPal identifica cada webhook por um ID, e nós o usamos para perguntar ao PayPal diretamente se uma dada mensagem é autêntica. Isso impede qualquer um de forjar um evento de "pago".

URL de sucesso e cancelamento

Configurações simples: onde o comprador chega depois de pagar ou desistir. Não são secretas.

Configurar

1. Abra o painel de desenvolvedor do PayPal

   Entre em developer.paypal.com. O PayPal oferece um Sandbox gratuito com contas de negócio e comprador falsas, para que você possa testar sem movimentar dinheiro real. Este guia percorre o Sandbox; o fluxo Live é idêntico, basta alternar o botão Sandbox / Live (canto superior esquerdo) e usar uma conta PayPal para Empresas. No painel, abra Apps & Credentials.

   ⤢
2. Crie um app

   Na página API Credentials, confirme que o botão Sandbox está selecionado e clique em Create App (canto superior direito).

   ⤢
3. Dê um nome e escolha Merchant

   Digite um App Name (por exemplo "Coin Moebius"), deixe o Type em Merchant, escolha a sua conta de negócio sandbox e clique em Create App.

   ⤢
4. Copie o seu Client ID e o Client secret

   O PayPal abre o seu novo app. Copie o Client ID e revele e copie o Secret key. (Você também pode copiar ambos a partir da linha Default Application na lista API Credentials.) Guarde-os.

   ⤢

   ⤢

   O Client secret é secreto, trate-o como uma senha. O app sandbox e o app de produção têm pares diferentes, portanto não os misture.

5. Adicione um webhook

   Role para baixo na página do app até a seção Sandbox Webhooks e clique em Add Webhook. No campo Webhook URL, cole o endereço de webhook do seu projeto PayPal (abaixo). Em seguida, escolha os eventos que o Coin Moebius escuta e Salve.

   • Pagamentos únicos: CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.DECLINED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, CUSTOMER.DISPUTE.CREATED.
   • Assinaturas (somente se você as vender): BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.UPDATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.PAYMENT.FAILED, PAYMENT.SALE.COMPLETED. Se você não cobra de forma recorrente, pule estes.
   • Com pressa? Selecionar All Events (o curinga no topo) também funciona, ignoramos tudo o que não usamos.

   https://api.coinmoebius.com/webhook/paypal/<your project id>

   ⤢

   O ID do seu projeto está abaixo do nome do projeto no painel do Coin Moebius; insira-o no endereço acima. O cartão do provedor conectado (último passo) mostra a mesma URL para referência.

6. Copie o Webhook ID

   O seu webhook agora aparece na lista Sandbox Webhooks. Copie o Webhook ID exibido ao lado dele. É assim que o Coin Moebius pede ao PayPal para confirmar que cada webhook é genuíno. Registre um webhook separado no sandbox e na produção.

   ⤢
7. De volta no Coin Moebius: Adicionar provedor → PayPal

   No seu projeto, abra a aba Provedores, clique em Adicionar provedor, escolha Conectar um serviço e selecione PayPal. Defina a sua URL de sucesso e a URL de cancelamento. Testando com credenciais de sandbox? Use a aba Test (opcional) e cole o Client ID, o Client secret e o Webhook ID lá, depois clique em Salvar. Indo direto para a produção? Use a aba Live. O grupo Test é tudo ou nada: os três campos, ou nenhum.

   ⤢
8. Você está conectado

   O PayPal agora aparece na sua aba Provedores com a data em que foi conectado (marcado como TEST quando você usou credenciais de sandbox). O cartão mostra a mesma URL de webhook que você colou no PayPal, além de Editar e Desconectar.

   ⤢
9. Teste com um comprador de sandbox

   Para pagar através de um checkout de teste, você precisa do seu login de comprador de sandbox. No PayPal, abra Testing Tools → Sandbox Accounts para ver as suas contas falsas de Empresa e Pessoal.

   ⤢
10. Obtenha os dados de login do comprador

    Abra a conta Personal (comprador) para ver as suas Login Info: a URL de sandbox, o e-mail e a senha. Entre em sandbox.paypal.com com esses dados quando um checkout de teste pedir que você pague. Nenhum dinheiro real se move.

    ⤢

Depois de conectar

Faça um pagamento de teste antes de ir ao ar:

1. Crie um produto e defina o Ambiente dele como Teste. Isso roda o produto nas suas credenciais de sandbox, para que você possa fazer um pedido completo sem mover dinheiro. (Se você pulou o conjunto de sandbox, um produto de Teste recai para a produção, então adicione-o primeiro.)
2. Coloque o botão de compra em uma página (um arquivo HTML local serve) apontado para o seu projeto.
3. Conclua o checkout pagando com a sua conta de comprador de sandbox.
4. Abra a aba Transações. Uma nova linha aparece, marcada como Teste. Quando o status dela chegar a succeeded, as suas credenciais e o webhook estão ambos funcionando de ponta a ponta.

Mude o Ambiente do produto para Produção quando você estiver pronto para pagamentos reais.

Solução de problemas

Comece com Verificar. No painel, clique em Verificar (ou Verificar credenciais de teste para o sandbox) para checar as suas credenciais de cliente.

A verificação falha.

Copie de novo o Client ID e o Client secret. O app de sandbox e o app de produção têm pares diferentes, então não os misture.

O pagamento se conclui mas o pedido fica pendente.

O Webhook ID deve vir do mesmo app e ambiente que as suas credenciais de cliente. Credenciais de produção precisam do webhook ID de produção. Confirme que a URL do webhook coincide.

Confirme de ponta a ponta.

PayPal Developer Dashboard → Webhooks Simulator: envie um evento de exemplo para a sua URL de webhook, depois observe o pedido atualizar.

Bom saber

Rotacionando segredos. Gere um novo client secret quando quiser, depois cole. Os campos secretos ficam em branco na edição.

Dúvidas? Join our Discord