Paypal Donation

[Chico Gois]

PayPal Donate — Extensão de doações para phpBB

Olá a todos,

Tenho o prazer de apresentar a extensão PayPal Donate, desenvolvida para comunidades phpBB que desejam receber doações, organizar campanhas de apoio e reconhecer seus apoiadores diretamente no fórum.

A extensão foi criada para ser simples de usar, mas com recursos suficientes para atender desde fóruns pequenos até comunidades que desejam uma gestão mais completa de doações.

Principais recursos

• Doações via PayPal com configuração simples pelo ACP.
• Página pública de doação com título, texto e botão configuráveis.
• Campanhas de apoio com meta, valor arrecadado e barra de progresso.
• Doações manuais registradas diretamente pelo administrador.
• Página pública de apoiadores, com opção para ocultar valores individuais.
• Doações anônimas para preservar a privacidade dos apoiadores.
• Grupo de apoiadores opcional para usuários que contribuírem.
• Badge no viewtopic para destacar apoiadores nas mensagens do fórum.
• Recompensas com validade, permitindo benefícios temporários ou vitalícios.
• Notificações por e-mail para agradecimento, aviso ao administrador e expiração de recompensas.
• Dashboard no ACP com estatísticas gerais das doações.
• Integração PayPal API/Webhook opcional para uso avançado.
• ACP organizado no menu esquerdo, seguindo o padrão administrativo do phpBB.
• Permissão administrativa própria para controlar quem pode gerenciar a extensão.

Modo simples ou avançado

A extensão pode ser usada de forma simples, apenas com o e-mail PayPal configurado, sem necessidade de API.

Para comunidades que desejam uma integração mais completa, também existe suporte opcional para PayPal API/Webhook, permitindo uma base preparada para confirmação automática de eventos de pagamento.

Campanhas e apoiadores

Com o sistema de campanhas, é possível definir uma meta de apoio, acompanhar o progresso e exibir publicamente o andamento da arrecadação.

Os administradores também podem registrar doações manualmente, marcar doações como anônimas, exibir apoiadores em uma página pública e vincular doações a usuários do fórum.

Reconhecimento dos apoiadores

A extensão permite destacar usuários apoiadores através de grupo phpBB e badge no viewtopic.

Também é possível definir validade para a recompensa, como 30 dias, 90 dias, 1 ano ou vitalícia.

Administração

O ACP foi dividido em seções próprias no menu esquerdo, facilitando a navegação:

• Visão geral
• Configurações
• Campanha
• Doações
• Apoiadores
• Recompensas
• Notificações
• PayPal API

Compatibilidade

• phpBB 3.3.x
• PHP compatível com phpBB 3.3
• Sem alterações no core do phpBB

Instalação

Envie a extensão para:

Código: Selecionar todos

ext/mundophpbb/paypaldonate/

Depois acesse:

Código: Selecionar todos

ACP > Personalizar > Gerenciar extensões

Ative a extensão e configure as opções em:

Código: Selecionar todos

ACP > Extensões > PayPal Donate

Observação

A integração PayPal API/Webhook é opcional. A extensão funciona normalmente no modo manual/simples, ideal para quem deseja apenas disponibilizar uma forma prática de receber apoio da comunidade.

Espero que esta extensão seja útil para fóruns que desejam incentivar contribuições, organizar campanhas e valorizar seus apoiadores.

Nome da extensão: PayPal Donate
Vendor/package: mundophpbb/paypaldonate
Versão inicial anunciada: 1.9.4
Compatibilidade: phpBB 3.3.x
Download: https://github.com/mundophpbb/paypaldonate

[Chico Gois]

Tutorial — Configurando PayPal API/Webhook na extensão PayPal Donate

Este tutorial explica como configurar a integração PayPal API/Webhook na extensão PayPal Donate para phpBB.

A integração é opcional. A extensão funciona normalmente sem API, usando o modo manual. A API/Webhook é indicada para quem deseja preparar a extensão para receber notificações automáticas de pagamento vindas do PayPal.

1. Requisitos

Antes de começar, você precisa de:

• Uma conta PayPal.
• Acesso ao PayPal Developer.
• A extensão PayPal Donate instalada e ativa no phpBB.
• URL pública do fórum acessível pela internet.
• HTTPS ativo no domínio.

O Webhook precisa de uma URL pública, pois o PayPal enviará notificações HTTP para o seu fórum quando determinados eventos ocorrerem. Segundo a documentação do PayPal, Webhooks são chamadas HTTPS enviadas pelo PayPal para um endpoint do seu sistema quando um evento correspondente acontece.

2. Acessar o PayPal Developer

Acesse o painel do PayPal Developer:

Código: Selecionar todos

https://developer.paypal.com/

Entre com sua conta PayPal.

Depois acesse a área de aplicações REST/API no painel Developer.

3. Criar uma aplicação REST

No PayPal Developer, procure a área:

Código: Selecionar todos

Apps & Credentials

Você verá normalmente dois ambientes:

• Sandbox — ambiente de testes.
• Live — ambiente real/produção.

Recomenda-se começar pelo Sandbox.

Clique em:

Código: Selecionar todos

Create App

Defina um nome para a aplicação, por exemplo:

Código: Selecionar todos

phpBB PayPal Donate

Depois crie a aplicação.

4. Copiar Client ID e Secret

Dentro da aplicação criada, o PayPal exibirá:

• Client ID
• Secret

Essas credenciais são usadas pela extensão para autenticar chamadas REST no PayPal. As APIs REST do PayPal usam OAuth 2.0; o Client ID e o Secret são trocados por um access token para autorizar chamadas à API.

No ACP do phpBB, acesse:

Código: Selecionar todos

ACP > Extensões > PayPal Donate > PayPal API

Preencha:

Código: Selecionar todos

Ativar API/Webhook: Sim
Ambiente: Sandbox
Client ID: cole o Client ID
Secret: cole o Secret

Salve as configurações.

Importante: não compartilhe o Secret publicamente. Ele deve ser tratado como senha.

5. Copiar a URL do Webhook da extensão

Na seção PayPal API da extensão, será exibida uma URL parecida com:

Código: Selecionar todos

https://seudominio.com/app.php/paypal-donate/webhook

Copie essa URL.

Essa é a URL que o PayPal usará para enviar notificações para o phpBB.

6. Criar o Webhook no PayPal

Volte ao PayPal Developer, dentro da aplicação criada.

Procure a área de Webhooks e clique para adicionar um novo Webhook.

No campo de URL, cole a URL exibida no ACP da extensão:

Código: Selecionar todos

https://seudominio.com/app.php/paypal-donate/webhook

Depois selecione os eventos desejados.

Para doações/pagamentos, o principal evento recomendado é:

Código: Selecionar todos

PAYMENT.CAPTURE.COMPLETED

Também pode ser útil selecionar eventos relacionados a pagamento pendente, negado, reembolsado ou revertido, dependendo de como você deseja acompanhar as transações.

Exemplos possíveis:

Código: Selecionar todos

PAYMENT.CAPTURE.COMPLETED
PAYMENT.CAPTURE.DENIED
PAYMENT.CAPTURE.REFUNDED
PAYMENT.CAPTURE.REVERSED
CHECKOUT.ORDER.APPROVED

Salve o Webhook.

7. Copiar o Webhook ID

Após criar o Webhook, o PayPal exibirá um identificador do Webhook.

Copie o Webhook ID.

Volte ao ACP do phpBB:

Código: Selecionar todos

ACP > Extensões > PayPal Donate > PayPal API

Cole o valor em:

Código: Selecionar todos

Webhook ID

Salve novamente.

O Webhook ID é necessário para a validação das notificações recebidas. A documentação do PayPal mostra que a validação de assinatura usa dados do cabeçalho da notificação junto com o Webhook ID.

8. Testar em Sandbox

Antes de usar em produção, teste em Sandbox.

No PayPal Developer, você pode usar contas de teste Sandbox para simular pagamentos.

Também é possível usar a área de eventos/Webhooks do PayPal Developer para acompanhar notificações enviadas, verificar falhas e reenviar eventos quando necessário.

Depois de um teste, volte ao ACP da extensão e verifique:

Código: Selecionar todos

PayPal Donate > PayPal API
PayPal Donate > Doações
PayPal Donate > Visão geral

Veja se a extensão recebeu algum evento e se a transação apareceu na lista.

9. Mudar para Live

Depois que tudo estiver funcionando em Sandbox, crie ou acesse a aplicação no ambiente Live.

Copie as credenciais Live:

Código: Selecionar todos

Client ID
Secret

Crie também um Webhook Live com a mesma URL pública da extensão.

Depois, no ACP:

Código: Selecionar todos

ACP > Extensões > PayPal Donate > PayPal API

Altere:

Código: Selecionar todos

Ambiente: Live
Client ID: Client ID Live
Secret: Secret Live
Webhook ID: Webhook ID Live

Salve.

10. Cuidados importantes

• Use Sandbox para testes.
• Use Live apenas quando estiver pronto para produção.
• Não publique o Client Secret.
• Use HTTPS no fórum.
• Confirme se a URL do Webhook é acessível externamente.
• Após alterar configurações, limpe o cache do phpBB se necessário.
• Verifique se o servidor não bloqueia requisições externas do PayPal.

11. Solução de problemas

O PayPal não envia eventos

Verifique se:

• O Webhook foi criado no mesmo ambiente configurado na extensão.
• A extensão está em Sandbox quando o Webhook é Sandbox.
• A extensão está em Live quando o Webhook é Live.
• A URL do Webhook está correta.
• O domínio usa HTTPS.

O evento chega, mas não é aceito

Verifique se:

• O Webhook ID foi copiado corretamente.
• O Client ID e Secret pertencem ao mesmo ambiente do Webhook.
• O relógio/horário do servidor está correto.
• Não há firewall bloqueando chamadas externas.

A extensão funciona sem API, mas não registra eventos automáticos

Isso normalmente indica que o modo manual está correto, mas o PayPal Developer ainda não está configurado corretamente.

Revise:

Código: Selecionar todos

Client ID
Secret
Ambiente Sandbox/Live
Webhook ID
URL do Webhook
Eventos selecionados

Resumo

A configuração básica segue esta ordem:

1. Criar aplicação REST no PayPal Developer.
2. Copiar Client ID e Secret.
3. Ativar API/Webhook no ACP da extensão.
4. Copiar a URL do Webhook exibida pela extensão.
5. Criar Webhook no PayPal Developer.
6. Selecionar eventos de pagamento.
7. Copiar o Webhook ID.
8. Colar o Webhook ID no ACP.
9. Testar em Sandbox.
10. Migrar para Live quando estiver validado.