AcapaPay · CodeIgniter SDK

Referência Rápida — Classe AcapaPay & Spark

Todas as chamadas abaixo assumem uma instância direta: $acapapay = new \AcapaPay\CodeIgniter\AcapaPay(); — não existe Facade neste pacote.

Métodos da Classe `AcapaPay`

Método	Retorno	Descrição
`autenticar()`	string	Autentica via OAuth2 Client Credentials e devolve um novo access token (sem cache).
`obterTokenCached($cacheDuration = 3300)`	string	Devolve o access token, reutilizando um token em cache (serviço de Cache do CodeIgniter) quando disponível.
`checkoutSession($userId, $planReferenceCode, $metadata = [], $successUrl = null, $cancelUrl = null)`	string	Cria sessão de checkout e devolve apenas o `url` de pagamento.
`criarSessaoPagamento(array $dados)`	array	Cria sessão de checkout e devolve a resposta completa; único método que permite sobrepor `amount`.
`criarFatura(array $dados)`	array	Cria uma Invoice (fatura) imutável representando a dívida/carrinho; via `POST /v1/billing/invoices`.
`criarCobranca($invoiceId, $paymentMethod, $customerPhone = null)`	array	Cria uma Charge (tentativa de pagamento) para uma Invoice existente; via `POST /v1/billing/invoices/{id}/charges`.
`consultarFatura($invoiceId)`	array	Consulta o estado atual de uma fatura; via `GET /v1/billing/invoices/{id}`.
`consultarStatusFatura($invoiceId)`	array	Consulta o `invoice_status` (pending, paid, expired, cancelled) para polling do frontend; via `GET /v1/billing/invoices/{id}/status`.
`simularPagamento($invoiceId)`	array	Marca uma fatura como paga instantaneamente em modo Sandbox; via `POST /v1/billing/invoices/{id}/simulate`. Não usar em produção.
`sincronizarPlanos(array $planos)`	array	Sincroniza (cria/atualiza) planos em lote; via `PUT /v1/billing/plans`. Usado internamente pelo comando `acapapay:sync-plans`.
`validarAssinaturaWebhook($payload, $signature)`	bool	Valida a assinatura HMAC-SHA256 de um payload de webhook contra `acapapay.webhookSecret`.
`testarConexao()`	array{sucesso: bool, mensagem: string}	Testa a autenticação OAuth2 e faz `GET /v1/ping`. Usado pelo comando `acapapay:test-connection`.
`renderIframe($checkoutUrl, array $opts = [])`	string	Devolve o HTML do iFrame de checkout pronto a imprimir. `$opts` aceita `height` (padrão `700px`) e `width` (padrão `100%`).

ℹ️

Checkout sem iFrame criarFatura(), criarCobranca(), consultarFatura()/consultarStatusFatura() e simularPagamento() compõem a API de Pagamento Direta — permite construir a tua própria interface de checkout (referência Multicaixa, prompt Multicaixa Express, ticket E-Kwanza) sem redirecionar nem embutir nenhum iFrame do SSO. O guia completo (fluxo passo-a-passo, prazos de validade por método de pagamento, formato do webhook dedicado) está documentado para o SDK Laravel e aplica-se da mesma forma aqui, pois são os mesmos endpoints M2M: API de Pagamento Direta →.

Comandos Spark

Comando	Descrição
`php spark acapapay:test-connection`	Testa a ligação e valida as credenciais no servidor central.
`php spark acapapay:sync-plans`	Sincroniza os planos locais (via `PlanoProviderInterface`) com o catálogo do AcapaPay.

Eventos CodeIgniter Disponíveis

Evento	Quando é Disparado	Payload (`$data`)
`acapapay:invoice.paid`	Webhook `invoice.paid` recebido e validado	`event`, `data` (inclui `invoice_id` e `metadata`)
`acapapay:invoice.failed`	Webhook `invoice.failed` recebido e validado	`event`, `data`
`acapapay:invoice.canceled`	Webhook `invoice.canceled` recebido e validado	`event`, `data`

O nome do evento é sempre acapapay: + o campo event bruto recebido no payload do webhook — outros tipos de evento futuros seguirão automaticamente o mesmo padrão sem necessidade de atualizar o pacote.

Rota Automática (Auto-Discovery)

Método	URI	Controller
POST	`/webhooks/acapapay`	`AcapaPay\CodeIgniter\Controllers\WebhookController::handle`

Variáveis de Ambiente (.env)

Chave	Obrigatório	Descrição
`acapapay.clientId`	Sim	Client ID (App ID) gerado no Painel de Developer do SSO.
`acapapay.clientSecret`	Sim	Client Secret gerado para a sua App.
`acapapay.webhookSecret`	Recomendado	Chave HMAC para validar a assinatura dos Webhooks.
`acapapay.modo`	Não	`sandbox` ou `producao` (em português — padrão: `producao`). Ignorado se `host`/`apiHost` customizados estiverem definidos.
`acapapay.host`	Não	URL customizada do servidor de identidade, sobrepõe a escolha baseada em `modo`.
`acapapay.apiHost`	Não	URL customizada da API, sobrepõe a escolha baseada em `modo`.
`acapapay.verifySsl`	Não	Desativa a verificação SSL (padrão: `true`); útil em desenvolvimento local com certificados self-signed.

Duas propriedades adicionais de configuração — organizationId (usado em criarFatura() para integrações multi-organização) e planoProvider (classe usada por acapapay:sync-plans) — não têm chave .env direta e devem ser definidas em app/Config/AcapaPay.php na sua aplicação, estendendo a config do pacote.