AcapaPay · CodeIgniter SDK

Iniciar um Pagamento (Checkout Session)

Como Funciona

Ao contrário do SDK Laravel, aqui não existe Facade nem service locator: o SDK é usado sempre por instância direta da classe AcapaPay\CodeIgniter\AcapaPay. Internamente o SDK pede um token OAuth2 (Client Credentials) — reutilizando um token em cache quando disponível via obterTokenCached() — cria a sessão de checkout, e devolve o URL de pagamento para redirecionar (ou embutir em iFrame) o utilizador.

Duas Formas de Criar a Sessão

O SDK expõe dois métodos equivalentes:

• checkoutSession() — espelha a assinatura do SDK Laravel e devolve apenas o url de redirecionamento (string).
• criarSessaoPagamento() — recebe um array associativo, devolve a resposta completa da API, e é o único que permite sobrepor pontualmente o amount do plano (ex: para descontos).

Assinatura de checkoutSession()

public function checkoutSession(
    mixed   $userId,             // ID do utilizador na sua base de dados
    string  $planReferenceCode,  // Referência do plano (ex: 'PRO_YEARLY')
    array   $metadata = [],      // Dados extras devolvidos no Webhook
    ?string $successUrl = null,  // URL para onde redirecionar após pagamento
    ?string $cancelUrl = null    // URL para onde redirecionar se o utilizador cancelar
): string // Devolve apenas o URL da sessão de checkout

Assinatura de criarSessaoPagamento()

/**
 * @param array{
 *   user_id: mixed,
 *   plan_reference_code: string,
 *   amount?: int,        // opcional: sobrepõe o preço do plano, em cêntimos
 *   currency?: string,   // usado apenas se 'amount' for definido (padrão: 'AOA')
 *   success_url?: string,
 *   cancel_url?: string,
 *   metadata?: array,
 * } $dados
 */
public function criarSessaoPagamento(array $dados): array // Devolve a resposta completa da API

Exemplo Completo no Controller (CodeIgniter 4)

<?php

namespace App\Controllers;

use AcapaPay\CodeIgniter\AcapaPay;
use CodeIgniter\Controller;

class PagamentoController extends Controller
{
    public function comprarPlano()
    {
        $userId = session()->get('user_id');
        $plano  = 'PRO_YEARLY';

        try {
            $acapapay = new AcapaPay();

            $urlDePagamento = $acapapay->checkoutSession(
                $userId,
                $plano,
                ['local_user_id' => $userId],
                site_url('pagamento/sucesso'),
                site_url('pagamento/cancelado')
            );

            return view('pagamento/checkout', ['urlDePagamento' => $urlDePagamento]);
        } catch (\Throwable $e) {
            return redirect()->back()->with('error', $e->getMessage());
        }
    }
}

Exemplo com criarSessaoPagamento() (com override de preço)

$acapapay = new AcapaPay();

$dados = $acapapay->criarSessaoPagamento([
    'user_id'             => $userId,
    'plan_reference_code' => 'PRO_YEARLY',
    'amount'              => 15000, // opcional: sobrepõe o preço do plano, em cêntimos
    'currency'            => 'AOA',
    'success_url'         => site_url('pagamento/sucesso'),
    'cancel_url'          => site_url('pagamento/cancelado'),
    'metadata'            => ['local_user_id' => $userId],
]);

$urlDePagamento = $dados['url'];

Embutir o Checkout com renderIframe()

Para manter o utilizador dentro do seu site sem redirecionamento, use o método renderIframe(), que devolve o HTML pronto a imprimir (não é um componente Blade — o SDK renderiza a sua própria view interna em src/Views/iframe.php):

public function renderIframe(string $checkoutUrl, array $opts = []): string
// $opts aceita 'height' (padrão '700px') e 'width' (padrão '100%')

<?= (new \AcapaPay\CodeIgniter\AcapaPay())->renderIframe($urlDePagamento, ['height' => '800px']) ?>