Pix na API da PushinPay: cobrança, QR Code, webhook idempotente e conciliação

Um guia prático com curl e PHP/Laravel, do token no sandbox até o checklist de produção, incluindo os erros que mais vejo nas integrações.

O bug de Pix que eu mais vejo em integração é o webhook que chega duas vezes. O cliente paga uma vez só, mas recebe dois e-mails de acesso, ou o estoque baixa em dobro. O código não tem nada de errado na sintaxe. Ele só partiu do pressuposto de que cada aviso chega uma única vez.

Sou cofundador e diretor de produtos da PushinPay. Passo boa parte da semana em conversa com times que estão ligando o Pix em loja virtual, plataforma de infoproduto ou ERP. As perguntas quase sempre são as mesmas: onde pego o token, como mostro o QR Code, como sei que o cliente pagou, o que faço quando o aviso chega repetido.

Neste texto eu junto as respostas. Tem curl, para testar no terminal, e PHP com Laravel, para levar ao projeto.

Antes do primeiro request

Você precisa de três coisas:

  1. Conta na PushinPay. O cadastro é em https://app.pushinpay.com.br/register.
  2. Token de API, gerado no painel. Ele vai em todo request no header Authorization: Bearer SEU_TOKEN.
  3. O host certo. Para homologação e testes, use o sandbox: api-sandbox.pushinpay.com.br. Em produção, é api.pushinpay.com.br. Os caminhos dos endpoints são iguais nos dois.

Mande Accept: application/json em todas as chamadas. Assim até a resposta de erro vem em JSON, e o seu código não precisa adivinhar o formato.

Para trocar de ambiente sem mexer no código, eu deixo host e token no .env:

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

E registro no config/services.php:

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

Gerando a cobrança

O endpoint é POST /api/pix/cashIn. O único campo que você precisa mandar é value, em centavos, com mínimo de 50 (R$ 0,50).

Os opcionais que eu uso em quase toda integração:

Campo Para quê
webhook_url URL que recebe o aviso quando o status muda
expires_in validade em segundos, de 300 (5 min) a 172800 (48 h)
description texto livre, até 255 caracteres
split_rules[] divide o valor entre contas: value em centavos e account_id
utms utm_source, utm_campaign, utm_medium, utm_content, utm_term

Uma cobrança de R$ 49,90 que vale por 30 minutos:

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": 4990, "expires_in": 1800, "description": "Pedido 1234", "webhook_url": "https://seusite.com.br/webhooks/pushinpay?pedido=1234" }' 

Repare que é 4990, não 49.90. Mandar o valor em reais é o erro mais comum do primeiro dia. Se o seu banco guarda decimal, converta antes de montar o payload, e evite float nessa conta.

Na resposta vêm:

  • id: identificador da transação. Salve no pedido, porque tudo depois depende dele.
  • qr_code: o Pix copia e cola.
  • qr_code_base64: a imagem do QR Code.
  • status: nasce como created.
  • value, end_to_end_id, payer_name, payer_national_registration e split_rules.

O ?pedido=1234 na webhook_url é proposital. Quando o aviso chegar, a própria URL já diz qual pedido é, sem depender do corpo da requisição.

O mesmo fluxo no Laravel

O cliente HTTP do Laravel dá conta sem pacote extra. No ponto em que o pedido é fechado:

use Illuminate\Support\Facades\Http; $resposta = Http::baseUrl(config('services.pushinpay.base_url')) ->withToken(config('services.pushinpay.token')) ->acceptJson() ->post('/api/pix/cashIn', [ 'value' => $pedido->total_centavos, 'expires_in' => 1800, 'description' => "Pedido {$pedido->id}", 'webhook_url' => route('webhooks.pushinpay', ['pedido' => $pedido->id]), ]) ->throw() ->json(); $pedido->update([ 'pushinpay_id' => $resposta['id'], 'pix_copia_cola' => $resposta['qr_code'], 'status' => 'aguardando_pagamento', ]); 

O ->throw() faz um 4xx ou 5xx virar exceção. Sem ele, um erro de validação passa em silêncio e você só descobre quando o $resposta['id'] não existe.

Mostrando o QR Code

A imagem sai direto do base64. Se o campo já vier com o prefixo data:image/png;base64,, use como está. Se não vier, acrescente o prefixo antes de jogar no src:

<img src="{{ $qrCodeBase64 }}" alt="QR Code Pix do pedido"> <input type="text" readonly value="{{ $pedido->pix_copia_cola }}"> 

Deixe o copia e cola sempre ao lado da imagem, de preferência com um botão de copiar. Quem compra pelo celular não tem como escanear a própria tela.

Quatro status, quatro decisões

A lógica do pedido gira em torno de quatro valores de status:

  • created: cobrança gerada, sem pagamento ainda.
  • paid: pago.
  • canceled: falhou, expirou ou foi cancelada.
  • refunded: estornada.

Na maioria dos sistemas o mapeamento é direto: paid libera o pedido, canceled devolve o estoque reservado, refunded dispara o fluxo de devolução.

O webhook

Quando o status muda, a PushinPay faz um POST na webhook_url. Se você não quiser mandar a URL em cada cobrança, dá para configurar um webhook por conta em /api/accounts/webhooks.

Com um segredo configurado, a requisição chega com os headers x-pushinpay-token e x-pushinpay-signature, este no formato sha256=<HMAC-SHA256>. Valide antes de qualquer outra coisa. A forma exata de montar a comparação está na documentação.

A regra que eu repito em toda conversa: o webhook é gatilho, não fonte da verdade. Recebeu o aviso, consulte a transação e decida com base no que a consulta devolveu. Isso vale para qualquer gateway, não é particularidade nossa.

A rota (lembre de tirá-la da verificação de CSRF):

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

O controller:

use Illuminate\Http\Request; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Http; class PushinPayWebhookController { public function __invoke(Request $request) { // valide aqui x-pushinpay-signature com o seu segredo $pedido = Pedido::findOrFail($request->query('pedido')); $transacao = Http::baseUrl(config('services.pushinpay.base_url')) ->withToken(config('services.pushinpay.token')) ->acceptJson() ->get("/api/transactions/{$pedido->pushinpay_id}") ->throw() ->json(); DB::transaction(function () use ($pedido, $transacao) { $pedido = Pedido::lockForUpdate()->find($pedido->id); if ($transacao['status'] === 'paid' && $pedido->status !== 'pago') { $pedido->update([ 'status' => 'pago', 'end_to_end_id' => $transacao['end_to_end_id'], ]); // liberar acesso, emitir nota, avisar o cliente } if ($transacao['status'] === 'canceled' && $pedido->status === 'aguardando_pagamento') { $pedido->update(['status' => 'cancelado']); } }); return response()->noContent(); } } 

O que esse código resolve:

  • Aviso repetido. O mesmo evento pode chegar mais de uma vez, inclusive ao mesmo tempo. O lockForUpdate dentro da transação faz a segunda requisição esperar a primeira terminar. Quando ela entra, o pedido já está pago e o if não passa. O acesso é liberado uma vez só. É exatamente o bug do começo do texto.
  • Status vindo da consulta. A decisão sai do GET /api/transactions/{id}, não do corpo do POST.
  • end_to_end_id salvo. É o identificador do Pix no sistema bancário. Quando o cliente diz "eu paguei", é com ele que o suporte encerra a conversa.

Um cuidado extra: tudo o que fala com o mundo de fora (e-mail, nota fiscal) fica mais seguro em um job disparado depois do commit. Se o e-mail sair dentro da transação e o banco der rollback, o cliente recebe um aviso de algo que não foi gravado.

Se o seu servidor cair e algum webhook falhar, dá para reenviar pelo painel ou pela API.

Consulta, estorno e comprovante

A consulta já apareceu no webhook. Junto com ela, mais dois endpoints entram cedo em quase toda integração:

# consultar curl https://api-sandbox.pushinpay.com.br/api/transactions/ID_DA_TRANSACAO \ -H "Authorization: Bearer SEU_TOKEN" -H "Accept: application/json" # estornar curl -X POST https://api-sandbox.pushinpay.com.br/api/transactions/ID_DA_TRANSACAO/refund \ -H "Authorization: Bearer SEU_TOKEN" -H "Accept: application/json" # comprovante curl https://api-sandbox.pushinpay.com.br/api/pix/voucher/ID_DA_TRANSACAO \ -H "Authorization: Bearer SEU_TOKEN" -H "Accept: application/json" 

Conciliação: a rede de segurança

Aviso perdido é raro, mas acontece: deploy na hora errada, firewall novo, certificado vencido. Por isso eu sempre coloco uma rotina agendada que pega pedidos parados há mais tempo que o expires_in e consulta a transação.

No Laravel 11, em routes/console.php:

use Illuminate\Support\Facades\Schedule; Schedule::call(function () { Pedido::where('status', 'aguardando_pagamento') ->where('created_at', '<', now()->subMinutes(35)) ->each(function ($pedido) { // mesma consulta e mesma lógica do controller do webhook }); })->everyTenMinutes(); 

A dica aqui é tirar a lógica de dentro do DB::transaction do controller e colocar numa classe própria, chamada pelos dois. Assim webhook e conciliação nunca divergem.

O caminho contrário: saque

Se a sua aplicação também paga alguém (repasse a afiliado, devolução manual), o saque é POST /api/pix/cashOut com:

  • value em centavos, mínimo 100 (R$ 1,00);
  • pix_key;
  • receiver_national_registration;
  • webhook_url.

A consulta fica em GET /api/transfers/{id}.

O token usado aqui precisa ter permissão de transferência. Minha recomendação é ter um token separado só para saque, guardado apenas no serviço que faz isso. Se o token do checkout vazar, ninguém consegue mandar dinheiro para fora com ele.

Erros que eu vejo com frequência

  • Valor em reais no lugar de centavos.
  • Webhook que libera o pedido com base no corpo da requisição, sem consultar a transação.
  • Webhook sem lock, que libera o mesmo pedido duas vezes.
  • Rota do webhook barrada pelo CSRF, que devolve 419 e nunca processa nada.
  • Só a imagem do QR Code na tela, sem o copia e cola.
  • Deploy em produção com o .env ainda apontando para o sandbox.

Checklist antes de ir para produção

  • [ ] Fluxo completo testado no sandbox: criar, pagar, receber webhook, consultar.
  • [ ] Assinatura do webhook validada.
  • [ ] Webhook idempotente, rodando dentro de transação no banco.
  • [ ] end_to_end_id salvo no pedido.
  • [ ] Rotina de conciliação para pedidos em created.
  • [ ] Token de saque separado, se houver saque.
  • [ ] PUSHINPAY_BASE_URL apontando para https://api.pushinpay.com.br e token de produção no .env.

Se travar em algum ponto, o time da PushinPay acompanha a integração sem custo. Na maioria dos casos ela fica pronta em menos de 12 horas.

Links