Search by

devkussema / acapapay-laravel

devkussema

SDK Oficial AcapaPay para integração rápida em aplicações Laravel.

Package info

github.com/devkussema/acapapay-laravel

pkg:composer/devkussema/acapapay-laravel

Statistics

Installs: 291

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.5.0 2026-11-08 19:05 UTC

This package is auto-updated.

Last update: 2026-11-15 18:18:09 UTC


README

Latest Version on Packagist Software License

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

Suporta Multicaixa Express (GPO) e Referência Multicaixa (REF) via AppyPay / EMIS, pagamentos internacionais em USD e criptomoeda via RedotPay (RDP), WiPay (WIP) e Reembolsos Automatizados (Refunds) com estorno direto no cartão do cliente.

Warning

Compatibilidade exclusiva: este pacote foi desenhado exclusivamente para o Laravel Framework (versões 9.x a 14.x) com PHP 8.1+. 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.
  • Reembolsos Automatizados (Novo na v1.5.0) — estornos totais ou parciais de cobranças (AcapaPay::refund()) com crédito imediato no cartão do cliente via Multicaixa Express.
  • Checkout hospedado — uma chamada (AcapaPay::checkoutSession()) devolve um URL pronto a redirecionar ou a embutir num <x-acapapay::iframe>.
  • API de pagamento direta (Headless) — constrói a tua própria interface de checkout (AcapaPay::direct()), sem redirecionar nem usar iFrame.
  • Pagamentos em USD/criptomoeda (RedotPay) — liquidação em USDT/USDC/BTC com interface pronta ou QR code nativo.
  • Webhooks validados por HMAC-SHA256, com eventos nativos do Laravel (AcapaPayPaymentReceived, AcapaPayInvoicePaid, AcapaPayInvoiceRefunded, AcapaPayInvoiceFailed, AcapaPayInvoiceExpired).
  • Exceções tipadas (ValidationException, AuthenticationException, ForbiddenException, etc.), todas compatíveis com catch (\Exception $e).
  • Modo Sandbox para testar todo o ciclo de vida (cobrança, liquidação, estorno) sem dinheiro real.
  • CLI de diagnóstico e sincronização (acapapay:test-connection e acapapay:sync-plans).

Instalação rápida

composer require devkussema/acapapay-laravel
ACAPAPAY_MODO=sandbox
ACAPAPAY_CLIENT_ID=o-teu-client-id
ACAPAPAY_CLIENT_SECRET=o-teu-client-secret
ACAPAPAY_WEBHOOK_SECRET=o-teu-webhook-secret
ACAPAPAY_BASE_URL=https://id.acapadev.me
php artisan acapapay:test-connection
use AcapaPay\Laravel\Facades\AcapaPay;

$url = AcapaPay::checkoutSession(
    userId: auth()->id(),
    planReference: 'PRO_MONTHLY',
    metadata: ['empresa_id' => 12],
    successUrl: url('/pagamento/sucesso'),
    cancelUrl: url('/pagamento/cancelado')
);

return redirect()->away($url);

📚 Documentação Oficial (v1.5.0 — Novembro 2026)

A documentação completa, versionada e atualizada está organizada na pasta docs/v1.5.0/:

# Ficheiro Conteúdo
01 Introdução e Arquitetura Visão geral do ecossistema, modos de integração e ciclo de vida.
02 Instalação e Configuração Requisitos, .env, publicação de config e teste de conectividade.
03 Checkout Hospedado checkoutSession(), createInvoice(), componentes Blade e iFrame.
04 Pagamento Direto via API Checkout Headless: Multicaixa Express (GPO), Referência (REF), Cripto (RDP).
05 Reembolsos e Estornos (Novo) Estorno total e parcial via API (AcapaPay::refund()), regras e TPA Virtual.
06 Webhooks e Eventos Assinatura HMAC, todos os eventos do SDK e Listeners práticos.
07 Sandbox e Testes Simulações instantâneas (simulate()), estornos de teste e túneis locais.
08 Sincronização de Planos Gestão centralizada de planos no AcapaDev ID (acapapay:sync-plans).
09 Tratamento de Erros Hierarquia de exceções, resiliência e boas práticas.
10 Referência Rápida (Cheat Sheet) Resumo de métodos da Facade, API direta, Enums e payloads.

Versões legadas de documentação encontram-se arquivadas em docs/v1.4.0/.

Changelog

Ver CHANGELOG.md para o histórico completo de versões.

Licença

Distribuído sob a licença MIT.