AcapaPay · CodeIgniter SDK

Webhooks — Confirmação Assíncrona de Pagamentos

Arquitetura

Quando uma fatura é paga, falha, ou é cancelada, o servidor AcapaPay envia um HTTP POST para o endpoint da sua aplicação. O SDK já regista automaticamente esta rota através de AcapaPay\CodeIgniter\Controllers\WebhookController::handle(), que trata de toda a segurança e processamento: valida a assinatura HMAC e, em seguida, dispara um evento nativo do CodeIgniter via Events::trigger() — não uma classe de evento Laravel como no SDK irmão.

Rota Registada Automaticamente (Auto-Discovery)

O pacote regista a seguinte rota automaticamente através do Auto-Discovery de rotas do CodeIgniter (ficheiro src/Config/Routes.php do pacote — não precisa de a adicionar ao seu app/Config/Routes.php):

POST /webhooks/acapapay
Controller: AcapaPay\CodeIgniter\Controllers\WebhookController::handle

Validação HMAC Automática

O WebhookController do SDK valida automaticamente a assinatura de cada pedido antes de disparar qualquer evento. O header verificado é X-AcapaDev-Signature, e o segredo usado é acapapay.webhookSecret:

// Lógica interna do SDK (AcapaPay::validarAssinaturaWebhook) — não precisa de escrever isto
$esperado = hash_hmac('sha256', $payload, $this->config->webhookSecret);

return hash_equals($esperado, $signature);

Se a assinatura ou o corpo do pedido estiverem ausentes, ou a assinatura for inválida, o controller devolve 401 sem disparar nenhum evento.

Escutar os Eventos no seu Projeto

Ao contrário do SDK Laravel (que dispara uma única classe de evento AcapaPayInvoicePaid), este pacote dispara um evento CodeIgniter distinto por tipo de notificação, prefixado com acapapay: seguido do campo event recebido no payload (ex: acapapay:invoice.paid, acapapay:invoice.failed, acapapay:invoice.canceled). Registe os listeners em app/Config/Events.php:

<?php

namespace Config;

use CodeIgniter\Events\Events;

// ... resto do ficheiro Events.php

Events::on('acapapay:invoice.paid', function (array $data) {
    $metadata    = $data['data']['metadata'] ?? [];
    $localUserId = $metadata['local_user_id'] ?? null;
    $invoiceId   = $data['data']['invoice_id'] ?? null;

    if (! $localUserId) {
        log_message('error', 'AcapaPay: local_user_id em falta na metadata do webhook.');
        return;
    }

    // Ativa a assinatura / marca a encomenda como paga na sua base de dados
});

Events::on('acapapay:invoice.failed', function (array $data) {
    // Trate a falha de pagamento (ex: notificar o utilizador)
});

Events::on('acapapay:invoice.canceled', function (array $data) {
    // Trate o cancelamento
});

Payload do Evento (Estrutura)

Cada listener recebe o array $data completo descodificado do JSON do webhook (o mesmo array passado a Events::trigger()):

Chave	Tipo	Descrição
event	string	Nome bruto do evento recebido (ex: invoice.paid), usado para compor o nome do evento CI disparado
data	array	Corpo com os detalhes da fatura, incluindo invoice_id e a metadata enviada no checkout
data.metadata	array	Os dados que enviou em metadata ao criar a sessão de checkout