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 quatro coisas:
- Conta na PushinPay. O cadastro é em https://app.pushinpay.com.br/register.
- Sandbox liberado pelo suporte. O sandbox só funciona depois que o suporte da PushinPay libera o acesso, e para isso a conta precisa estar cadastrada em produção.
-
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.
A documentação exige Accept: application/json e Content-Type: application/json em todas as chamadas.
Para trocar de ambiente sem mexer no código, eu deixo host e token no .env, junto com o valor do header do webhook configurado no painel (mais sobre ele adiante):
PUSHINPAY_BASE_URL=https://api-sandbox.pushinpay.com.br
PUSHINPAY_TOKEN=SEU_TOKEN
PUSHINPAY_WEBHOOK_TOKEN=VALOR_DO_HEADER_CONFIGURADO_NO_PAINEL
E registro no config/services.php:
'pushinpay' => [
'base_url' => env('PUSHINPAY_BASE_URL'),
'token' => env('PUSHINPAY_TOKEN'),
'webhook_token' => env('PUSHINPAY_WEBHOOK_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"
}'
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 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'),
])
->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. O campo qr_code_base64 já vem com o prefixo data:image/png;base64, e vai direto no src:
<p>A PUSHIN PAY atua exclusivamente como processadora de pagamentos e não possui qualquer responsabilidade pela entrega, suporte, conteúdo, qualidade ou cumprimento das obrigações relacionadas aos produtos ou serviços oferecidos pelo vendedor.</p>
<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.
O aviso de que a PushinPay é só a processadora de pagamentos é obrigatório. Toda cobrança precisa mostrá-lo ao comprador de forma visível, no momento da oferta e antes da finalização do pagamento, com o texto que está na página Criar PIX da documentação. A mesma página cita o item 4.10 dos Termos de Uso como origem da regra e avisa que o não cumprimento pode gerar penalizações e até bloqueio da conta.
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 envia uma notificação para a webhook_url com id, value, status e end_to_end_id no corpo.
A PushinPay não assina o webhook. A segurança vem de um header customizado que você configura no painel, em Configurações, e que é enviado em todos os webhooks. Ele chega como x-pushinpay-token, com o valor que você definiu. Valide antes de qualquer outra coisa: compare esse header com o valor salvo usando hash_equals e responda 401 se não bater. Se o valor salvo estiver vazio, recuse também; senão, uma configuração esquecida aceita qualquer requisição.
A regra que eu repito em toda conversa: header validado, status do webhook aplicado de forma idempotente. Não consulte a API a cada aviso. O próprio webhook diz o novo status; o seu trabalho é garantir que ele veio da PushinPay e que aplicar o mesmo aviso duas vezes não muda nada.
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;
class PushinPayWebhookController
{
public function __invoke(Request $request)
{
$esperado = (string) config('services.pushinpay.webhook_token');
$recebido = (string) $request->header('x-pushinpay-token', '');
if ($esperado === '' || ! hash_equals($esperado, $recebido)) {
abort(401);
}
$pedido = Pedido::where('pushinpay_id', $request->input('id'))->firstOrFail();
$status = $request->input('status');
$endToEndId = $request->input('end_to_end_id');
DB::transaction(function () use ($pedido, $status, $endToEndId) {
$pedido = Pedido::lockForUpdate()->find($pedido->id);
if ($status === 'paid' && $pedido->status !== 'pago') {
$pedido->update([
'status' => 'pago',
'end_to_end_id' => $endToEndId,
]);
// liberar acesso, emitir nota, avisar o cliente
}
if ($status === 'canceled' && $pedido->status === 'aguardando_pagamento') {
$pedido->update(['status' => 'cancelado']);
}
});
return response()->noContent();
}
}
O que esse código resolve:
-
Requisição falsa. Sem o
x-pushinpay-tokencerto, a resposta é 401 e nada é processado. Com o valor salvo vazio, também. -
Aviso repetido. O mesmo evento pode chegar mais de uma vez, inclusive ao mesmo tempo; se a entrega falhar, a PushinPay tenta de novo até 3 vezes. 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 do webhook validado. A decisão sai do
statusdo aviso, depois de conferir o header e localizar o pedido peloidda transação, sem chamada extra à API. -
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 mesmo depois das 3 tentativas, dá para reenviar pelo painel.
Consulta, estorno e comprovante
A consulta não faz parte do fluxo do webhook. Ela serve para um caso: o cliente avisa que pagou e o pedido ainda não mudou. Mesmo aí, no máximo 1 consulta por minuto; intervalo menor pode bloquear a conta. Nada de consultar em laço. Junto com ela, mais dois endpoints entram cedo em quase toda integração:
# consultar (só quando o cliente avisar que pagou, no máximo 1 vez por minuto)
curl https://api-sandbox.pushinpay.com.br/api/transactions/ID_DA_TRANSACAO \
-H "Authorization: Bearer SEU_TOKEN" -H "Accept: application/json" -H "Content-Type: 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" -H "Content-Type: 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" -H "Content-Type: application/json"
Conciliação: a rede de segurança
Aviso perdido é raro, mas acontece: deploy na hora errada, firewall novo, certificado vencido. A PushinPay já tenta 3 vezes, e o que falhar dá para reenviar pelo painel. A rede de segurança do seu lado não é consultar a API em lote: é saber quais pedidos ficaram parados e dar ao cliente um botão "Já paguei".
Uma rotina agendada que só olha o seu banco e avisa o time, sem chamar a API. No Laravel 11, em routes/console.php:
use Illuminate\Support\Facades\Schedule;
Schedule::call(function () {
$parados = Pedido::where('status', 'aguardando_pagamento')
->where('created_at', '<', now()->subMinutes(35))
->count();
if ($parados > 0) {
// alertar o time para conferir e reenviar webhooks pelo painel
}
})->everyTenMinutes();
E o botão "Já paguei", que consulta a transação no máximo 1 vez por minuto na conta inteira. A documentação diz só que consultas diretas são autorizadas a cada 1 minuto e não informa se o limite vale para a conta ou para cada transação. Por cautela, eu uso uma chave de limite só para todos os pedidos.
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\RateLimiter;
$liberado = RateLimiter::attempt('pushinpay-consulta', 1, function () use ($pedido) {
$transacao = Http::baseUrl(config('services.pushinpay.base_url'))
->withToken(config('services.pushinpay.token'))
->acceptJson()
->withHeaders(['Content-Type' => 'application/json'])
->get("/api/transactions/{$pedido->pushinpay_id}")
->throw()
->json();
// mesma lógica idempotente do controller do webhook
}, 60);
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 botão "Já paguei" 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 processa o aviso sem validar o
x-pushinpay-token, ou que aceita tudo quando o valor salvo está vazio. - Webhook que consulta a API a cada aviso, ou rotina que consulta em laço, arriscando o bloqueio da conta.
- 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, e o webhook com header errado recusado com 401.
- [ ] Header
x-pushinpay-tokencomparado comhash_equalsao valor salvo; 401 se não bater ou se o valor salvo estiver vazio. - [ ] Webhook idempotente, rodando dentro de transação no banco.
- [ ]
end_to_end_idsalvo no pedido. - [ ] Aviso visível, antes do pagamento, de que a PushinPay é só a processadora de pagamentos.
- [ ] Alerta para pedidos parados em
createde botão "Já paguei" com no máximo 1 consulta por minuto na conta inteira. - [ ] Token de saque separado, se houver saque.
- [ ]
PUSHINPAY_BASE_URLapontando parahttps://api.pushinpay.com.br, token de produção ePUSHINPAY_WEBHOOK_TOKENno.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

Top comments (0)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.