Pix em Laravel com a API da PushinPay: client HTTP, webhook com HMAC 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 e põe na fila. E um job consulta a transação antes de mexer no pedido. 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

São dois ambientes:

  • Sandbox: api-sandbox.pushinpay.com.br, para homologação e testes de integração.
  • 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. 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" }' 

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 por cobrança. Também dá para configurar uma URL por conta.

Na resposta vêm id, qr_code (o Pix copia e cola), qr_code_base64 (a imagem do QR), status e value. Depois do pagamento a transação passa a ter também end_to_end_id, payer_name e payer_national_registration.

Configuração no Laravel

.env:

PUSHINPAY_BASE_URL=https://api-sandbox.pushinpay.com.br PUSHINPAY_TOKEN=SEU_TOKEN PUSHINPAY_WEBHOOK_SECRET=SEU_SEGREDO 

config/services.php:

'pushinpay' => [ 'base_url' => env('PUSHINPAY_BASE_URL'), 'token' => env('PUSHINPAY_TOKEN'), 'webhook_secret' => env('PUSHINPAY_WEBHOOK_SECRET'), ], 

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() ->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(); } 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(); } } 

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'], ]); 

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. Antes de montar o src da imagem, confira se o qr_code_base64 já vem com o prefixo data:image/.... Se você adicionar o prefixo duas vezes, a imagem quebra.

A rota e o controller do webhook

Quando o status da transação muda, a PushinPay faz um POST na webhook_url. Você pode mandar a URL em cada cobrança, como no client acima, ou configurar uma por conta em /api/accounts/webhooks.

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:

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

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.

Com um segredo configurado, a requisição chega com os headers x-pushinpay-token e x-pushinpay-signature: sha256=<HMAC-SHA256>. No exemplo abaixo eu calculo o HMAC sobre o corpo bruto da requisição. Antes de ir para produção, confirme na documentação qual conteúdo entra no cálculo.

<?php namespace App\Http\Controllers; use App\Jobs\SyncPushinPayTransaction; use Illuminate\Http\Request; class PushinPayWebhookController { public function __invoke(Request $request) { $secret = config('services.pushinpay.webhook_secret'); abort_if(blank($secret), 500, 'Webhook secret não configurado'); $expected = 'sha256=' . hash_hmac('sha256', $request->getContent(), $secret); $received = (string) $request->header('x-pushinpay-signature'); abort_unless(hash_equals($expected, $received), 401); // confira o formato do payload na documentação $id = $request->input('id'); abort_if(blank($id), 422); SyncPushinPayTransaction::dispatch($id); return response()->noContent(); } } 

Incluí duas checagens que não estavam no meu primeiro rascunho. A primeira é o abort_if para o segredo vazio. Sem ele, um .env incompleto faz o HMAC ser calculado com chave vazia, e qualquer um que souber disso consegue gerar uma assinatura válida. 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 a consulta à API terminar.

O job: consultar, travar, comparar

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

  • O mesmo evento pode chegar mais de uma vez. O tratamento precisa ser idempotente.
  • Não confie só no corpo do webhook. Confirme o status consultando a transação.

Por isso o job ignora o status do webhook e pergunta direto para a API com GET /api/transactions/{id}:

<?php namespace App\Jobs; use App\Models\Payment; use App\Services\PushinPay; 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]; public function __construct(public string $id) {} public function handle(PushinPay $pushinPay): void { $transaction = $pushinPay->find($this->id); DB::transaction(function () use ($transaction) { $payment = Payment::where('pushinpay_id', $transaction['id']) ->lockForUpdate() ->firstOrFail(); if ($payment->status === $transaction['status']) { return; // evento repetido, nada a fazer } $payment->update([ 'status' => $transaction['status'], 'end_to_end_id' => $transaction['end_to_end_id'] ?? null, ]); if ($transaction['status'] === 'paid') { $payment->order->markAsPaid(); } }); } } 

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.
  • 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 a consulta falhar por timeout ou instabilidade de rede.

Se algum webhook falhar do seu lado (servidor fora do ar, deploy no meio do caminho), dá para reenviar pelo painel ou pela API.

Os quatro status

  • created: cobrança gerada, pagamento pendente.
  • paid: pago.
  • canceled: falhou, expirou ou foi cancelado.
  • refunded: estornado.

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 vai para refunded e o webhook avisa. Como o job já trata qualquer mudança de status, você não precisa de código extra para receber essa notificação.
  • 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" 

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, ]), ]); 

Para o webhook, monte a assinatura no próprio teste com hash_hmac('sha256', $corpo, $segredo). Depois verifique que a assinatura certa devolve 204 e a errada devolve 401.

Checklist antes de trocar para produção

  • Cobrança criada e paga no sandbox, com o pedido marcado como pago pelo job.
  • Mesmo webhook enviado duas vezes, sem efeito duplicado.
  • Webhook com assinatura errada recusado com 401.
  • Segredo do webhook preenchido no .env do servidor.
  • 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