AcapaPay · Laravel SDK

API de Pagamento Direta (sem iFrame)

Além do checkout hospedado (redirecionamento ou <x-acapapay::iframe>), o AcapaPay expõe uma API de pagamento direta: um conjunto de endpoints M2M em bruto que permitem à tua aplicação construir a própria interface de checkout, sem nunca redirecionar o utilizador para o SSO nem embutir nenhum iFrame.

1. Autenticação

Todos os endpoints abaixo são M2M (machine-to-machine), protegidos pelo mesmo middleware client do Passport usado pelo resto do AcapaPay. Obtém um token OAuth2 client_credentials com as mesmas credenciais (ACAPAPAY_CLIENT_ID / ACAPAPAY_CLIENT_SECRET) já usadas para checkoutSession():

POST https://api.{dominio}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...&scope=*

Usa o access_token devolvido como Authorization: Bearer <token> em todos os pedidos seguintes.

2. Fluxo completo

1. POST /v1/billing/invoices — cria a fatura (cliente, itens, referência, metadata).
2. POST /v1/billing/invoices/{id}/charges — gera a cobrança (REF, GPO, EKZ, RDP ou WIP) para essa fatura.
3. A tua app mostra os dados devolvidos (referência/entidade, prompt Multicaixa Express, ticket/QR code E-Kwanza, ou o link de pagamento em cripto) na tua própria UI.
4. GET /v1/billing/invoices/{id}/status — usado em polling (a cada poucos segundos) até a fatura ficar paid. Internamente há um rate-limit de 15s por fatura antes de voltar a consultar o gateway externo — pedidos mais frequentes devolvem o último estado conhecido sem novo pedido externo.
5. Assim que a fatura é confirmada como paga (via polling ou via webhook do gateway), o SSO dispara o webhook invoice.paid para o webhook_url configurado na tua App, assinado em X-AcapaDev-Signature (HMAC-SHA256) — ver Webhooks.

Todas as cobranças e reconciliações geradas por esta API ficam visíveis no admin do SSO (Faturação → detalhe da fatura), exatamente como as geradas pela página de checkout hospedada.

Webhook URL dedicado para faturação (opcional)

Por omissão, o invoice.paid é enviado para o mesmo webhook_url usado pelos eventos de identidade (user.logout, user.updated, user.role_updated). Se o teu sistema de faturação for um serviço separado do que trata a sessão/autenticação, podes configurar um "Webhook URL de Faturação" dedicado no painel Developer → Webhooks & Eventos da tua app.

• Quando preenchido, só o evento invoice.paid passa a ir para esse URL — os restantes eventos continuam a ir para o webhook_url geral.
• Quando vazio, o comportamento é o de sempre: invoice.paid continua a ir para o webhook_url geral. Nenhuma app já integrada precisa de mudar nada.
• Usa o mesmo webhook_secret e a mesma assinatura HMAC do webhook_url geral — não há segredo separado por endpoint.

3. Como Apresentar o Pagamento em Cripto ao Utilizador — 2 Fluxos

Guia completo do dólar, com exemplos do SDK: Pagamentos em USD (Cripto).

Isto aplica-se especificamente ao método RDP (RedotPay/criptomoeda), que é o único onde a diferença entre os dois fluxos é significativa. Para REF/GPO/EKZ a API direta já te dá a referência ou o ticket em texto, prontos a mostrar — não há QR code nem redirecionamento externo envolvido nesses métodos.

Quando geras uma cobrança RDP, tens de escolher uma de duas formas de levar o utilizador a pagar. Nenhuma é objetivamente "melhor" — a escolha depende de quanto controlo visual precisas e de quanto trabalho de implementação estás disposto a fazer.

Fluxo 1 — Redirecionar (recomendado por omissão)

É o mais simples, e é o que a nossa própria página de checkout hospedado usa internamente. Chamas o endpoint de cobrança, recebes um data.pay_url, e envias o utilizador para lá — ponto final.

$response = Http::withToken($token)->post("{$apiHost}/v1/billing/invoices/{$invoiceId}/charges", [
    'payment_method' => 'RDP',
]);

$payUrl = $response->json('data.pay_url');

return redirect($payUrl);
// ou, se estiveres a responder a um pedido AJAX/fetch feito pelo teu frontend:
// return response()->json(['pay_url' => $payUrl]);
// e no frontend: window.open(data.pay_url, '_blank');

O que o utilizador vê ao chegar a esse pay_url: uma página hospedada pela RedotPay (não é tua, nem nossa) com a lista de carteiras suportadas (MetaMask, Phantom, Trust Wallet, Coinbase, TronLink, etc.), cada uma já com o seu próprio QR code desenhado e pronto a digitalizar. A RedotPay trata de tudo: gerar as imagens de QR, detetar se o visitante está em mobile ou desktop, abrir o deep-link correto se tiver a carteira instalada no telemóvel, etc.

Fluxo 2 — Construir a tua própria interface com o QR code embutido

Se quiseres que o utilizador nunca saia da tua página — por exemplo, mostrar o QR code dentro de um modal da tua app, ao lado do teu logótipo — usa o array data.paymentMethods devolvido pela API de cobrança.

Estrutura de cada item em data.paymentMethods (nem todos os campos vêm sempre preenchidos — depende da carteira):

{
  "id": "phantom",
  "name": "Phantom",
  "logo": "https://staticsource1.redotpay.com/aquirer/wallets/phantom.svg",
  "webUrl": "https://phantom.app/ul/browse/...",    // abrir num browser desktop
  "webQrCode": "https://phantom.app/ul/browse/...", // converter em QR (desktop)
  "h5Url": "https://phantom.app/ul/browse/...",     // abrir num browser mobile
  "h5QrCode": "https://phantom.app/ul/browse/...",  // converter em QR (mobile/H5)
  "appUrl": "https://phantom.app/ul/browse/...",    // deep-link direto para a app
  "appQrCode": null
}

Uma cobrança RDP típica devolve entre 12 e 13 carteiras neste array (MetaMask, Phantom, Trust Wallet, Binance Wallet, OKX Wallet, Bitget Wallet, TokenPocket, ImToken, Coinbase, Rainbow, TronLink, RedotPay e Coinbase Pay — confirmado com uma chamada real ao ambiente sandbox).

Gerar a imagem do QR code

Há duas formas de o fazer — escolhe consoante onde preferes que o trabalho aconteça:

Opção A — Gerar no servidor (PHP), com simplesoftwareio/simple-qrcode:

composer require simplesoftwareio/simple-qrcode

{{-- resources/views/checkout/cripto.blade.php --}}
@foreach ($wallets as $wallet)
    @if ($wallet['webQrCode'])
        <div class="carteira">
            <img src="{{ $wallet['logo'] }}" alt="{{ $wallet['name'] }}">
            <p>{{ $wallet['name'] }}</p>
            {{-- SimpleQrCode desenha o SVG do QR diretamente a partir do link --}}
            {!! QrCode::size(220)->generate($wallet['webQrCode']) !!}
        </div>
    @endif
@endforeach

Opção B — Gerar no browser (JavaScript), com uma lib tipo qrcode: útil se o teu checkout for uma SPA (Vue/React) e quiseres evitar uma dependência PHP extra.

<canvas id="qr-phantom"></canvas>

<script src="https://cdn.jsdelivr.net/npm/qrcode/build/qrcode.min.js"></script>
<script>
    // 'linkDaCarteira' é o valor de wallet.webQrCode que já devolveste do backend
    QRCode.toCanvas(document.getElementById('qr-phantom'), linkDaCarteira);
</script>

Se detetares que o visitante está num telemóvel (user agent, ou uma media query no frontend), o mais correto é usares h5QrCode em vez de webQrCode, ou até nem mostrares QR nenhum e usares antes um botão "Abrir carteira" apontado a appUrl — porque num telemóvel não faz sentido pedir ao utilizador para digitalizar um QR code com o próprio telemóvel.

Qual escolher?

4. Exemplo Completo (Laravel)

<?php

use Illuminate\Support\Facades\Http;

class PagamentoDiretoController extends Controller
{
    protected function tokenM2M(): string
    {
        $response = Http::asForm()->post(config('acapapay.host') . '/oauth/token', [
            'grant_type'    => 'client_credentials',
            'client_id'     => config('acapapay.client_id'),
            'client_secret' => config('acapapay.client_secret'),
            'scope'         => '*',
        ]);

        return $response->json('access_token');
    }

    public function criarFaturaECobranca(Request $request)
    {
        $token = $this->tokenM2M();
        $apiHost = config('acapapay.api_host');

        // 1. Criar a fatura
        $invoice = Http::withToken($token)->post("{$apiHost}/v1/billing/invoices", [
            'customer_name'  => $request->user()->name,
            'customer_email' => $request->user()->email,
            'items'          => [
                ['description' => 'Plano PRO', 'quantity' => 1, 'unit_price' => 15000],
            ],
            'app_reference'  => 'pedido-' . $request->user()->id,
        ])->json();

        // 2. Gerar a cobrança (ex: Referência Multicaixa)
        $charge = Http::withToken($token)->post(
            "{$apiHost}/v1/billing/invoices/{$invoice['invoice_id']}/charges",
            ['payment_method' => 'REF']
        )->json();

        // $charge['data'] contém a referência/entidade a mostrar na tua UI
        // $charge['expires_at'] é o prazo de validade da cobrança (ver tabela abaixo)

        return response()->json($charge);
    }
}

5. Endpoints

POST /v1/billing/invoices

Cria a fatura. Um pagamento nunca existe sem estar associado a uma fatura.

Resposta 201:

{
  "status": "success",
  "invoice_id": "9b123a45-...",
  "pay_url": "https://pay.acapadev.com/9b123a45-...",
  "total": 15000,
  "currency": "AOA"
}

POST /v1/billing/invoices/{id}/charges

Cria uma cobrança para a fatura {id}.

Resposta 201:

{
  "status": "success",
  "payment_method": "REF",
  "is_mock": false,
  "expires_at": "2026-08-12T18:53:06+01:00",
  "data": { "...": "payload bruto devolvido pelo gateway" }
}

expires_at (ISO 8601) é o prazo de validade normalizado da cobrança — guarda-o na tua BD/cache para saberes quando deixar de mostrar a referência ao utilizador e/ou pedir uma nova cobrança. Vem sempre neste campo, independentemente do método (o gateway devolve o prazo em formatos diferentes consoante o método — o AcapaPay normaliza por ti). Prazos observados em produção:

GET /v1/billing/invoices/{id}/status também devolve este expires_at (dentro de data.transaction), recalculado a partir dos mesmos dados guardados — útil se a tua app recarregar a página e precisar de saber quanto tempo falta sem ter guardado o valor original.

Erros: 422 se a fatura já estiver paid/processing_verification; 500 com {"error": "..."} em caso de falha de comunicação com o gateway.

GET /v1/billing/invoices/{id}/status

Consulta (e tenta atualizar, respeitando o rate-limit de 15s) o estado atual da fatura.

{
  "status": "success",
  "data": {
    "invoice_status": "paid",
    "paid_at": "2026-08-09T12:34:56+00:00",
    "transaction": {
      "payment_method": "REF",
      "status": "completed",
      "gateway_reference": "INV1A2B3C4D5E",
      "expires_at": "2026-08-12T18:53:06+01:00"
    }
  }
}

POST /v1/billing/invoices/{id}/simulate

Apenas em ambiente sandbox: marca a fatura como paga imediatamente (cria uma transação sandbox_test e dispara o webhook invoice.paid), sem depender do gateway real. Devolve 403 fora de sandbox.

6. Erros

Todos os erros seguem {"error": "mensagem"}, com o código HTTP a indicar a categoria: