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:
- Conta na PushinPay. O cadastro é em https://app.pushinpay.com.br/register.
- Token de API, gerado no painel. Ele vai em todo request no header
Authorization: Bearer SEU_TOKEN. - 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 comocreated. -
value,end_to_end_id,payer_name,payer_national_registrationesplit_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
lockForUpdatedentro da transação faz a segunda requisição esperar a primeira terminar. Quando ela entra, o pedido já estápagoe oifnã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_idsalvo. É 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:
-
valueem 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
.envainda 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_idsalvo no pedido. - [ ] Rotina de conciliação para pedidos em
created. - [ ] Token de saque separado, se houver saque.
- [ ]
PUSHINPAY_BASE_URLapontando parahttps://api.pushinpay.com.bre 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
- Site: https://pushinpay.com.br
- Cadastro: https://app.pushinpay.com.br/register
- Painel (token e webhooks): https://app.pushinpay.com.br/app
- YouTube: @PUSHINpaybr
- LinkedIn: company/pushin-pay

