acapapay-laravel maintained by devkussema
AcapaPay Laravel SDK
O AcapaPay Laravel 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 Laravel — Multicaixa (Referência e Express), E-Kwanza, pagamentos em USD/criptomoeda via RedotPay, e (desde a v1.4.0) WiPay, um novo checkout hospedado em AOA.
[!WARNING] Compatibilidade exclusiva: este pacote foi desenhado exclusivamente para o Laravel Framework. Tem uma proteção em runtime que impede a sua execução em ambientes PHP puro ou noutras frameworks.
Funcionalidades principais
- Autenticação automática — gestão transparente de tokens M2M (OAuth2 Client Credentials), com cache, retentativa automática em 401, e retentativa em falhas de rede.
- Checkout hospedado — uma chamada (
checkoutSession()) devolve um URL pronto a redirecionar ou a embutir num<x-acapapay::iframe>. - API de pagamento direta — constrói a tua própria interface de checkout (
AcapaPay::direct()), sem redirecionar nem usar iFrame. - Pagamentos em USD/criptomoeda (RedotPay) — com duas formas de apresentar ao utilizador: redirecionar, ou o teu próprio QR code embutido.
- Webhooks validados por HMAC, com eventos nativos do Laravel (
AcapaPayPaymentReceived,AcapaPayInvoicePaid,AcapaPayInvoiceFailed,AcapaPayInvoiceExpired). - Exceções tipadas (
ValidationException,AuthenticationException, etc.), todas compatíveis comcatch (\Exception $e). - Modo Sandbox para testar todo o fluxo sem gerar cobranças reais.
- CLI de diagnóstico (
acapapay:test-connection) e de sincronização de planos (acapapay:sync-plans).
Instalação rápida
composer require devkussema/acapapay-laravel
ACAPAPAY_HOST=https://id.acapadev.com
ACAPAPAY_API_HOST=https://api.acapadev.com
ACAPAPAY_CLIENT_ID=o-teu-client-id
ACAPAPAY_CLIENT_SECRET=o-teu-client-secret
ACAPAPAY_WEBHOOK_SECRET=o-teu-webhook-secret
php artisan acapapay:test-connection
use AcapaPay\Laravel\Facades\AcapaPay;
$url = AcapaPay::checkoutSession(
auth()->id(),
'PRO_MONTHLY',
[],
url('/pagamento/sucesso'),
url('/pagamento/cancelado')
);
return redirect($url);
Isto é só o essencial para arrancar — para tudo o resto (config completa, iFrame, API direta, cripto, webhooks, erros, sandbox, sync de planos), ver a documentação completa abaixo.
📚 Documentação Completa
| # | Ficheiro | Conteúdo |
|---|---|---|
| 1 | Instalação e Configuração | Requisitos, .env, todas as chaves de config, comando de diagnóstico. |
| 2 | Checkout Hospedado | checkoutSession(), createInvoice(), componente <x-acapapay::iframe>. |
| 3 | API de Pagamento Direta | Construir o teu próprio checkout: AcapaPay::direct(), ChargeResult, polling. |
| 4 | Pagamentos em USD/Cripto (RedotPay) | Os 2 fluxos de apresentar o pagamento (redirecionar vs. QR próprio), geração de QR code, e o que o pacote não cobre (Payment Links do dashboard RedotPay). |
| 5 | Webhooks e Eventos | Como o webhook funciona, todos os eventos disponíveis, exemplos de listener. |
| 6 | Tratamento de Erros | A hierarquia de exceções e como as apanhar. |
| 7 | Sandbox e Testes | Simular pagamentos sem gerar cobranças reais, webhooks locais com túnel. |
| 8 | Sincronização de Planos | acapapay:sync-plans, toAcapaPayFormat(). |
| 9 | Referência Rápida | Todas as tabelas (métodos, eventos, exceções, config) num só sítio. |
Estes ficheiros são a única fonte de documentação mantida deste pacote (substituem o antigo
docs.html, que ficou desatualizado e foi removido). Se encontrares alguma divergência entre esta documentação e o código, por favor abre uma issue.
📚 Documentação v2 (recomendado — WiPay + RedotPay)
Desde a v1.4.0, se a tua app só usa os métodos hospedados mais recentes — WiPay (WIP) e RedotPay (RDP) —, esta documentação alternativa é mais direta (não passa por REF/GPO/EKZ). A documentação v1 acima continua válida e não foi alterada.
| # | Ficheiro | Conteúdo |
|---|---|---|
| 1 | Checkout Hospedado | checkoutSession(), createInvoice(), iFrame — para WiPay e RedotPay. |
| 2 | API de Pagamento Direta | AcapaPay::direct(), chargeWithWipay(), chargeWithCrypto(), ChargeResult. |
| 3 | Webhooks e Eventos | Por que o webhook é obrigatório para WiPay (sem endpoint de consulta de estado). |
| 4 | Referência Rápida | Tabela comparativa WIP vs. RDP e resumo de tudo. |
Changelog
Ver CHANGELOG.md para o histórico de versões.
Licença
Distribuído sob a licença MIT.