AcapaPay · CodeIgniter SDK
Introdução e Funcionalidades Principais
O AcapaPay CodeIgniter SDK (devkussema/acapapay-codeigniter, v1.2.0) é 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. Trata automaticamente da autenticação OAuth2 Machine-to-Machine (M2M) com cache de token persistente, expõe um helper de iFrame pronto a usar, e garante que os eventos de pagamento chegam à sua aplicação de forma segura via HMAC, disparando eventos nativos do CodeIgniter.
🔐 Autenticação M2M Automática
Gestão transparente de Access Tokens via OAuth2 Client Credentials, com cache persistente entre requests usando o serviço de Cache do CodeIgniter.
💳 Checkout Integrado
Cria sessões de pagamento com checkoutSession() ou criarSessaoPagamento() a partir de uma instância direta da classe AcapaPay.
🧩 Helper de iFrame
O método renderIframe() devolve o HTML do checkout pronto a embutir, com deteção automática de pagamento concluído via postMessage.
🔔 Webhooks & Eventos CodeIgniter
Recebe notificações de pagamento com validação HMAC e dispara eventos nativos via Events::trigger() (ex: acapapay:invoice.paid).
🔬 Modo Sandbox
Simula pagamentos completos com simularPagamento(), sem afetar dados reais nem gateways de produção.
🔄 Sincronização de Planos
Comando spark acapapay:sync-plans, orientado por uma PlanoProviderInterface implementada na sua aplicação (sem depender de uma Model Eloquent).
Compatibilidade Exclusiva — CodeIgniter 4.4+
Este pacote foi desenhado exclusivamente para o CodeIgniter 4.4+ (composer.json exige codeigniter4/framework: ^4.4 e php: ^8.1). Não é compatível com Laravel nem com PHP puro fora de uma aplicação CodeIgniter. Para Laravel, use o pacote dedicado.
Principais Diferenças Face ao SDK Laravel
Apesar de resolverem o mesmo problema, os dois SDKs têm arquiteturas distintas — não presuma que a API é idêntica:
| Aspeto | AcapaPay Laravel | AcapaPay CodeIgniter |
|---|---|---|
| Acesso ao SDK | Facade AcapaPay:: | Instância direta: new AcapaPay() (sem Facade/service locator) |
| Checkout | checkoutSession() | checkoutSession() e criarSessaoPagamento() (este permite sobrepor amount) |
| Interface embutida | Componente Blade | Helper renderIframe($url) que devolve uma string HTML |
| Rota de webhook | Registada pelo ServiceProvider | Registada via Auto-Discovery do CodeIgniter (src/Config/Routes.php) |
| Eventos disparados | Classe de evento Laravel AcapaPayInvoicePaid | Eventos nativos CodeIgniter acapapay:invoice.paid, acapapay:invoice.failed, acapapay:invoice.canceled |
| Sincronização de planos | Lê diretamente uma Model Eloquent | PlanoProviderInterface (listarPlanos() / marcarSincronizado()) implementada pela app host |
| Comandos CLI | php artisan acapapay:* | php spark acapapay:* |
| Chave de ambiente do modo | acapapay.mode = production / sandbox | acapapay.modo = producao / sandbox (em português) |