DEV Community

David William Balbino
David William Balbino

Posted on Edited on

Pix em Laravel com a API da PushinPay: client HTTP, webhook com token e job idempotente

Pix em Laravel com a API da PushinPay: client HTTP, webhook com token e job idempotente

O jeito que eu estruturo uma integração Pix em Laravel: testo tudo no sandbox antes e trato o webhook repetido sem marcar o pedido como pago duas vezes.

Eu sou o David, cofundador e diretor de produtos da PushinPay. Quando um dev me pergunta como organizar o Pix num projeto Laravel, eu costumo dar a mesma resposta. Uma classe pequena fala com a API. Um controller de webhook só valida o header e põe na fila. E um job atualiza o pedido com o status do webhook, de forma idempotente. Aqui está esse roteiro, com o código e os erros que eu mais vejo nas integrações.

Antes do PHP: token, hosts e um curl

O token é gerado no painel da PushinPay e vai em toda requisição, com estes headers:

  • Authorization: Bearer SEU_TOKEN
  • Accept: application/json
  • Content-Type: application/json

São dois ambientes:

  • Sandbox: api-sandbox.pushinpay.com.br, para homologação e testes de integração. Ele não vem liberado: primeiro você faz o cadastro em produção e depois pede ao suporte da PushinPay a liberação do sandbox. Sem isso, o sandbox não funciona.
  • Produção: api.pushinpay.com.br.

Se a sua aplicação só recebe Pix, um token comum resolve. Para fazer saque (Pix out), o token precisa ter permissão de transferência. Na conta também dá para ativar token 2FA e controle por IP.

Antes de abrir o editor, eu crio uma cobrança no sandbox direto pelo terminal. Com o sandbox já liberado pelo suporte, se der erro aqui, o problema está no token ou no payload, não no seu código:

curl -X POST https://api-sandbox.pushinpay.com.br/api/pix/cashIn \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 1990,
    "expires_in": 3600,
    "description": "Pedido 1042",
    "webhook_url": "https://sua-app.com.br/api/webhooks/pushinpay"
  }'
Enter fullscreen mode Exit fullscreen mode

O que cada campo aceita:

  • value: em centavos. 1990 = R$ 19,90. O mínimo é 50 (R$ 0,50).
  • expires_in: em segundos, de 300 a 172800 (5 minutos a 48 horas).
  • description: até 255 caracteres.
  • webhook_url: opcional, enviado em cada cobrança. O webhook só é enviado se esse campo estiver configurado.

Na resposta vêm id, qr_code (o Pix copia e cola), qr_code_base64 (a imagem do QR), status, value, webhook_url, split_rules, end_to_end_id, payer_name e payer_national_registration. Na criação, esses três últimos vêm com valor null. Eles só são preenchidos depois do pagamento.

Configuração no Laravel

.env:

PUSHINPAY_BASE_URL=https://api-sandbox.pushinpay.com.br
PUSHINPAY_TOKEN=SEU_TOKEN
PUSHINPAY_WEBHOOK_TOKEN=VALOR_DO_HEADER_CONFIGURADO_NO_PAINEL
Enter fullscreen mode Exit fullscreen mode

config/services.php:

'pushinpay' => [
    'base_url' => env('PUSHINPAY_BASE_URL'),
    'token' => env('PUSHINPAY_TOKEN'),
    'webhook_token' => env('PUSHINPAY_WEBHOOK_TOKEN'),
],
Enter fullscreen mode Exit fullscreen mode

Na hora de ir para produção, você troca a PUSHINPAY_BASE_URL e o token. O código continua igual.

O client

Uma classe só para a API, usando o client HTTP do próprio Laravel. Ela fica fácil de mockar nos testes, e o resto da aplicação não precisa saber de URL nem de header.

<?php

namespace App\Services;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;

class PushinPay
{
    private function http(): PendingRequest
    {
        return Http::baseUrl(config('services.pushinpay.base_url'))
            ->withToken(config('services.pushinpay.token'))
            ->acceptJson()
            ->contentType('application/json')
            ->timeout(10);
    }

    public function createCharge(int $cents, string $description, int $expiresIn = 3600): array
    {
        return $this->http()->post('/api/pix/cashIn', [
            'value' => $cents,
            'description' => mb_substr($description, 0, 255),
            'expires_in' => $expiresIn,
            'webhook_url' => route('webhooks.pushinpay'),
        ])->throw()->json();
    }

    // Só quando o cliente avisar que pagou, no máximo 1 consulta por minuto.
    public function find(string $id): array
    {
        return $this->http()->get("/api/transactions/{$id}")->throw()->json();
    }

    public function refund(string $id): array
    {
        return $this->http()->post("/api/transactions/{$id}/refund")->throw()->json();
    }
}
Enter fullscreen mode Exit fullscreen mode

O ->throw() transforma resposta 4xx/5xx em exceção. Prefiro assim a descobrir lá na frente que salvei um pagamento com id nulo.

Criando a cobrança no checkout

No controller do checkout, a cobrança é criada e o retorno vai para uma tabela payments ligada ao pedido:

$charge = $pushinPay->createCharge(1990, "Pedido {$order->id}");

$order->payment()->create([
    'pushinpay_id' => $charge['id'],
    'status' => $charge['status'],
    'value' => $charge['value'],
    'qr_code' => $charge['qr_code'],
]);
Enter fullscreen mode Exit fullscreen mode

Três cuidados que evitam chamado de suporte:

  • Centavos num lugar só. Se o valor vem de formulário, valide antes de chamar a API ('value' => 'required|integer|min:50') e converta reais para centavos uma única vez. Quando a conversão aparece em dois lugares, cedo ou tarde alguém cobra 100 vezes o valor.
  • Copia e cola visível. Mostre o QR Code e, logo abaixo, o texto do qr_code com um botão de copiar. Quem compra pelo celular quase sempre paga pelo copia e cola.
  • Imagem do QR. O qr_code_base64 já vem com o prefixo (data:image/png;base64,...). Use o valor como está no src da imagem e não acrescente o prefixo. Se ele aparecer duas vezes, a imagem quebra.

Além desses cuidados, há uma regra obrigatória: a documentação da PushinPay exige que o comprador veja, de maneira clara, destacada e acessível, um aviso de que a PushinPay atua apenas como processadora de pagamentos. O aviso vale para todos os canais de venda e precisa aparecer no momento da oferta e antes da finalização do pagamento, de preferência no checkout. Colocar o aviso junto do QR Code e do copia e cola ajuda, mas sozinho não cumpre a regra.

A rota e o controller do webhook

Quando o status da transação muda, a PushinPay envia uma notificação para a webhook_url que você mandou na cobrança, como no client acima. Se a cobrança for criada sem webhook_url, nenhum webhook é enviado.

A rota fica em routes/api.php, que não passa pela verificação de CSRF. Lembre que o Laravel coloca o prefixo /api nessas rotas, então a URL final é /api/webhooks/pushinpay. No Laravel 11 ou mais novo, esse arquivo não existe por padrão: crie com php artisan install:api.

Route::post('/webhooks/pushinpay', PushinPayWebhookController::class)
    ->name('webhooks.pushinpay');
Enter fullscreen mode Exit fullscreen mode

Um erro comum em desenvolvimento é usar localhost como webhook_url. A PushinPay precisa conseguir chegar até essa URL, então ela tem que ser um endereço público.

A PushinPay não assina o webhook. A segurança é um header customizado que você configura no painel (Configurações): ele é enviado em todos os webhooks e chega como x-pushinpay-token, com o valor que você definiu. O endpoint compara esse header com o valor salvo no .env e recusa o que não bater. O corpo traz id, value, status (created, paid ou canceled, segundo a documentação) e end_to_end_id.

<?php

namespace App\Http\Controllers;

use App\Jobs\SyncPushinPayTransaction;
use Illuminate\Http\Request;

class PushinPayWebhookController
{
    public function __invoke(Request $request)
    {
        $expected = (string) config('services.pushinpay.webhook_token');
        $received = (string) $request->header('x-pushinpay-token');

        abort_if($expected === '', 401);
        abort_unless(hash_equals($expected, $received), 401);

        $id = $request->input('id');
        $status = $request->input('status');
        abort_if(blank($id) || blank($status), 422);

        SyncPushinPayTransaction::dispatch($id, $status, $request->input('end_to_end_id'));

        return response()->noContent();
    }
}
Enter fullscreen mode Exit fullscreen mode

Incluí duas checagens que não estavam no meu primeiro rascunho. A primeira é o abort_if para o valor salvo vazio. Sem ele, um .env incompleto faz o endpoint aceitar qualquer requisição que chegue sem o header, porque string vazia é igual a string vazia. A segunda é o hash_equals em vez de ===, porque ele compara em tempo constante.

O controller faz pouco de propósito: valida, põe na fila e responde. Em produção, use uma fila de verdade com worker rodando. Com QUEUE_CONNECTION=sync, o webhook fica esperando o job terminar.

O job: travar, comparar, atualizar

Duas boas práticas que valem para qualquer webhook de pagamento:

  • O mesmo evento pode chegar mais de uma vez. A PushinPay tenta 3 vezes se a entrega falhar. O tratamento precisa ser idempotente.
  • Valide o header antes de usar o corpo. Com o x-pushinpay-token conferido no controller, o job usa o status que veio no webhook. Não consulte a API a cada webhook nem em laço: consulta de status (GET /api/transactions/{id}) é só para quando o cliente avisar que pagou, no máximo 1 por minuto. Intervalo menor pode bloquear a conta.

Por isso o job recebe o status do webhook e só cuida de aplicar a mudança uma vez:

<?php

namespace App\Jobs;

use App\Models\Payment;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\DB;

class SyncPushinPayTransaction implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 5;
    public array $backoff = [10, 30, 60, 120];

    // Status que não podem mais ser aplicados depois do status da chave.
    private const REGRESSIONS = [
        'canceled' => ['created'],
        'paid' => ['created', 'canceled'],
        'refunded' => ['created', 'paid', 'canceled'],
    ];

    public function __construct(
        public string $id,
        public string $status,
        public ?string $endToEndId = null,
    ) {}

    public function handle(): void
    {
        DB::transaction(function () {
            $payment = Payment::where('pushinpay_id', $this->id)
                ->lockForUpdate()
                ->firstOrFail();

            if ($payment->status === $this->status) {
                return; // evento repetido, nada a fazer
            }

            if (in_array($this->status, self::REGRESSIONS[$payment->status] ?? [], true)) {
                return; // webhook atrasado, não volta o status
            }

            $payment->update([
                'status' => $this->status,
                'end_to_end_id' => $this->endToEndId ?? $payment->end_to_end_id,
            ]);

            if ($this->status === 'paid') {
                $payment->order->markAsPaid();
            }
        });
    }
}
Enter fullscreen mode Exit fullscreen mode

O que cada parte resolve:

  • lockForUpdate impede que dois workers processem o mesmo pagamento ao mesmo tempo.
  • A comparação de status faz o evento repetido virar no-op.
  • A lista REGRESSIONS ignora um webhook atrasado que levaria o pagamento para trás, como um created ou canceled chegando para um pagamento que já está como paid ou refunded no seu banco, ou um created chegando para uma cobrança que já está como canceled (expirada ou cancelada), que voltaria a ficar pendente.
  • O end_to_end_id fica salvo porque é ele que identifica o Pix no sistema bancário. Quando alguém precisar rastrear um pagamento, é esse número que vai pedir.
  • $tries e $backoff fazem o job tentar de novo se o banco falhar por timeout ou instabilidade.

Se algum webhook falhar do seu lado (servidor fora do ar, deploy no meio do caminho), a PushinPay tenta 3 vezes e, depois disso, dá para reenviar pelo painel.

Os quatro status

  • created: cobrança gerada, pagamento pendente.
  • paid: pago.
  • canceled: falhou, expirou ou foi cancelado.
  • refunded: estornado. É status da transação; o corpo do webhook na documentação só lista created, paid e canceled.

O canceled por expiração é o que mais aparece e o que menos recebe atenção. Quando a cobrança expira, libere o estoque reservado e deixe o cliente gerar uma cobrança nova sem montar o carrinho de novo.

Estorno e comprovante

Esses dois endpoints costumam ficar para depois e fazem falta no primeiro atendimento:

  • Estorno: POST /api/transactions/{id}/refund. A transação fica com status refunded. A documentação diz que a webhook_url recebe as informações de pagamento ou estorno. O exemplo de corpo só mostra created, paid e canceled, e o job já aceita refunded quando ele chegar.
  • Comprovante: GET /api/pix/voucher/{id}. Serve para o suporte responder rápido quando o cliente diz que já pagou.
curl https://api-sandbox.pushinpay.com.br/api/pix/voucher/ID_DA_TRANSACAO \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
Enter fullscreen mode Exit fullscreen mode

Testes automatizados sem chamar a API

Como todo o acesso passa pela classe PushinPay, dá para simular as respostas com Http::fake e testar o checkout no CI sem depender de rede:

use Illuminate\Support\Facades\Http;

Http::fake([
    '*/api/pix/cashIn' => Http::response([
        'id' => 'tx_teste',
        'qr_code' => '...',
        'qr_code_base64' => '...',
        'status' => 'created',
        'value' => 1990,
    ]),
]);
Enter fullscreen mode Exit fullscreen mode

Para o webhook, defina services.pushinpay.webhook_token no próprio teste e mande o header x-pushinpay-token no postJson. Depois verifique que o valor certo devolve 204, e que valor errado, header ausente ou valor salvo vazio devolvem 401.

Checklist antes de trocar para produção

  • Sandbox liberado pelo suporte da PushinPay.
  • Cobrança criada e paga no sandbox, com o pedido marcado como pago pelo job.
  • Aviso de que a PushinPay atua apenas como processadora de pagamentos em todos os canais de venda, de maneira clara, destacada e acessível, no momento da oferta e antes da finalização do pagamento.
  • Mesmo webhook enviado duas vezes, sem efeito duplicado.
  • Webhook com x-pushinpay-token errado ou ausente recusado com 401.
  • Header customizado configurado no painel e o mesmo valor preenchido no .env do servidor.
  • Nenhuma consulta à API por webhook nem em laço; consulta só quando o cliente avisar que pagou, no máximo 1 por minuto.
  • Cobrança expirada tratada (estoque liberado, mensagem para o cliente).
  • Estorno testado de ponta a ponta.
  • Worker da fila rodando e monitorado.
  • Token de produção só no .env do servidor, nunca no repositório.

Se travar em algum ponto, o time da PushinPay acompanha a integração sem custo. Em geral a gente fecha em menos de 12 horas.

Links

Top comments (0)