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_TOKENAccept: application/jsonContent-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"
}'
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
config/services.php:
'pushinpay' => [
'base_url' => env('PUSHINPAY_BASE_URL'),
'token' => env('PUSHINPAY_TOKEN'),
'webhook_token' => env('PUSHINPAY_WEBHOOK_TOKEN'),
],
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();
}
}
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_codecom um botão de copiar. Quem compra pelo celular quase sempre paga pelo copia e cola. -
Imagem do QR. O
qr_code_base64já vem com o prefixo (data:image/png;base64,...). Use o valor como está nosrcda 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');
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();
}
}
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-tokenconferido 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();
}
});
}
}
O que cada parte resolve:
-
lockForUpdateimpede que dois workers processem o mesmo pagamento ao mesmo tempo. - A comparação de status faz o evento repetido virar no-op.
- A lista
REGRESSIONSignora um webhook atrasado que levaria o pagamento para trás, como umcreatedoucanceledchegando para um pagamento que já está comopaidourefundedno seu banco, ou umcreatedchegando para uma cobrança que já está comocanceled(expirada ou cancelada), que voltaria a ficar pendente. - O
end_to_end_idfica salvo porque é ele que identifica o Pix no sistema bancário. Quando alguém precisar rastrear um pagamento, é esse número que vai pedir. -
$triese$backofffazem 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ó listacreated,paidecanceled.
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 statusrefunded. A documentação diz que awebhook_urlrecebe as informações de pagamento ou estorno. O exemplo de corpo só mostracreated,paidecanceled, e o job já aceitarefundedquando 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"
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, 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-tokenerrado ou ausente recusado com 401. - Header customizado configurado no painel e o mesmo valor preenchido no
.envdo 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
.envdo 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
- Site: https://pushinpay.com.br
- Cadastro: https://app.pushinpay.com.br/register
- Painel (token e webhooks): https://app.pushinpay.com.br/app
- LinkedIn: linkedin.com/company/pushin-pay
- YouTube: @PUSHINpaybr

Top comments (0)