AcapaPay · Laravel SDK · v2

Iniciar um Pagamento (Checkout Session)

Como Funciona

O SDK comunica com o servidor central AcapaPay em duas fases sequenciais e automáticas: pede um token OAuth (Client Credentials), cria a sessão de checkout, e devolve o URL de pagamento para redirecionar o utilizador. Tudo isto acontece numa única chamada AcapaPay::checkoutSession(). O token OAuth é obtido e descartado automaticamente — nunca precisa de o gerir manualmente.

Assinatura do Método

AcapaPay::checkoutSession(
    mixed  $userId,          // ID do utilizador na sua base de dados
    string $planReference,   // Referência do plano (ex: 'PRO_MONTHLY')
    array  $metadata = [],   // Dados extras que quer receber de volta no Webhook
    string $successUrl,      // URL para onde redirecionar após pagamento
    string $cancelUrl,       // URL para onde redirecionar se o utilizador cancelar
    ?string $currency = null,        // 'AOA' (omissão, WIP) ou 'USD' (RDP)
    ?string $preferredMethod = null, // 'WIP' ou 'RDP'
): string // Devolve o URL seguro da sessão de checkout

Exemplo — WiPay (AOA, omissão)

<?php

namespace App\Http\Controllers;

use AcapaPay\Laravel\Facades\AcapaPay;

class AssinaturaController extends Controller
{
    public function iniciarCheckout(Request $request)
    {
        $plano = Plano::where('code', $request->plano_code)->firstOrFail();

        try {
            $urlPagamento = AcapaPay::checkoutSession(
                auth()->id(),
                $plano->reference_code,
                [
                    'local_user_id'  => auth()->id(),
                    'local_order_id' => $plano->id,
                    'plano_name'     => $plano->name,
                ],
                route('assinatura.sucesso'),
                route('assinatura.cancelado')
                // sem currency/preferredMethod: assume WIP em AOA
            );

            return view('assinatura.checkout', compact('urlPagamento', 'plano'));

        } catch (\Exception $e) {
            return back()->with('error', 'Não foi possível iniciar o pagamento: ' . $e->getMessage());
        }
    }

    public function sucesso()
    {
        // Nota: a confirmação real vem pelo Webhook, não por esta rota.
        return view('assinatura.sucesso');
    }
}

Exemplo — RedotPay (USD/cripto)

use AcapaPay\Laravel\Enums\Currency;
use AcapaPay\Laravel\Enums\PaymentMethod;

$urlPagamento = AcapaPay::checkoutSession(
    auth()->id(),
    $plano->reference_code,
    ['local_user_id' => auth()->id(), 'local_order_id' => $plano->id],
    route('assinatura.sucesso'),
    route('assinatura.cancelado'),
    currency: Currency::USD,
    preferredMethod: PaymentMethod::RDP,
);

Detalhes completos sobre a escolha de moeda e os dois fluxos de apresentação do QR code da RedotPay: WiPay + RedotPay — Pagamentos (v2).