Download the PHP package devkussema/acapapay-codeigniter without Composer

AcapaPay CodeIgniter SDK

O AcapaPay CodeIgniter SDK é a biblioteca oficial para integrar de forma rápida e segura a gateway de pagamentos centralizada do ecossistema AcapaDev em qualquer projeto baseado no CodeIgniter 4.

Este pacote trata automaticamente da comunicação OAuth2 (Server-to-Server), com cache de token persistente, e expõe uma view pronta a usar para apresentar o checkout sem fricções (através de iFrames otimizados e bidirecionais).

[!WARNING] Compatibilidade Exclusiva: Este pacote foi desenhado exclusivamente para o CodeIgniter 4.

Funcionalidades Principais

• Autenticação Automática: Gestão transparente de Tokens M2M (OAuth2) via Client Credentials, com cache persistente entre requests usando o serviço de Cache do CodeIgniter (file, redis, memcached, conforme configurado em app/Config/Cache.php).
• Modo Sandbox/Produção: troca automática entre ambientes através da variável acapapay.modo.
• View de iFrame: um helper renderIframe() que devolve o HTML do checkout pronto a embutir, e que reage automaticamente quando a fatura é paga pelo utilizador.
• Validação de Webhooks (HMAC): receção segura das notificações de pagamento baseada numa chave secreta, disparando eventos nativos do CodeIgniter (Events::trigger).
• CLI Diagnostic: comando spark nativo para testar a saúde da conexão entre o teu servidor e o SSO central.
• Rota de Webhook Auto-descoberta: o pacote regista POST webhooks/acapapay automaticamente via Auto-Discovery do CodeIgniter (não precisas de editar app/Config/Routes.php).
• Sincronização de Planos: comando spark acapapay:sync-plans que envia o teu catálogo local (preços/produtos/modelos) para o AcapaPay em lote — necessário porque a criação de sessão de checkout exige um plan_reference_code previamente registado no AcapaPay.

1. Instalação

Estender a configuração (opcional)

Por padrão os valores vêm das variáveis de ambiente (ver secção 2). Se precisares de lógica extra, podes criar app/Config/AcapaPay.php na tua aplicação estendendo a config do pacote:

O helper config('AcapaPay') do CodeIgniter resolve automaticamente para a tua subclasse, se existir.

2. Configuração (Variáveis de Ambiente)

A tua aplicação precisa de se identificar perante o AcapaPay (SSO). Cria uma "OAuth App" no painel do SSO e adiciona as seguintes credenciais ao teu ficheiro .env:

3. Teste de Diagnóstico e Conexão (spark)

Antes de escrever qualquer código, o pacote fornece um comando de diagnóstico que envia um Ping seguro à infraestrutura central. Isto valida se as credenciais .env estão corretas e se os firewalls não estão a bloquear a ligação.

• Se tudo estiver correto, verás uma mensagem de sucesso a verde no terminal.
• Se algo falhar (ex: IP bloqueado ou segredo errado), será devolvido um relatório de erro a vermelho.

4. Sincronizar Planos (obrigatório antes do primeiro checkout)

A API de checkout do AcapaPay exige um plan_reference_code já registado — não aceita apenas um valor avulso (amount). Antes de criar sessões de checkout, o teu catálogo local (preços, produtos, modelos) precisa de ser sincronizado como "planos" no AcapaPay.

Passo 1 — implementa o PlanoProviderInterface na tua aplicação:

Passo 2 — regista o provider em app/Config/AcapaPay.php:

Passo 3 — corre a sincronização sempre que os preços mudarem:

Isto autentica, envia todos os planos ativos em lote (PUT /v1/billing/plans) e grava de volta o id que o AcapaPay atribuiu a cada plano, via marcarSincronizado(). Corre este comando manualmente (ou por um botão no painel de administração) sempre que criares ou editares um item do catálogo — antes de tentar criar um checkout para esse item.

5. Iniciar um Pagamento (Checkout)

O SDK é usado por instância direta — não existem Facades em CodeIgniter 4.

Exemplo no teu Controller (por plano):

Exemplo com criarSessaoPagamento() (também requer plan_reference_code):

criarSessaoPagamento() faz o mesmo que checkoutSession(), mas devolve a resposta completa (não só a url) e permite sobrepor o preço do plano pontualmente via amount:

6. Integrar Interface (view de iFrame)

Para manter o utilizador dentro do teu site, usa o helper renderIframe(), que já escuta os eventos de sucesso/cancelamento transmitidos pelo SSO Central via postMessage:

[!NOTE] O componente deteta magicamente eventos disparados pela página de sucesso no AcapaDev e relança-os como CustomEvent (acapapay-success / acapapay-cancel) no window — basta escutares esses eventos em JavaScript no teu lado.

7. Escutar Webhooks (Atualizar Encomendas)

Quando a transação for paga com sucesso (ou falhar), o servidor central envia um Webhook POST para a tua aplicação.

O SDK regista automaticamente a rota POST webhooks/acapapay (via Auto-Discovery do CodeIgniter — confirma que discoverInComposer está true em app/Config/Modules.php, que é o padrão numa instalação nova). O pacote valida a assinatura HMAC e dispara um evento nomeado do CodeIgniter para cada tipo de evento recebido, ex: acapapay:invoice.paid, acapapay:invoice.failed, acapapay:invoice.canceled.

Regista o listener em app/Config/Events.php:

[!TIP] Se o teu projeto já tem uma rota de webhook própria noutro caminho, confirma que não há sobreposição antes de ativar ambos.

Licença

Distribuído sob a licença MIT.