DEV Community

David William Balbino
David William Balbino

Posted on Edited on Originally published at dev.to

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

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 quatro coisas:

  1. Conta na PushinPay. O cadastro é em https://app.pushinpay.com.br/register.
  2. 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.
  3. Token de API, gerado no painel. Ele vai em todo request no header Authorization: Bearer SEU_TOKEN.
  4. 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
Enter fullscreen mode Exit fullscreen mode

E registro no config/services.php:

'pushinpay' => [
    'base_url' => env('PUSHINPAY_BASE_URL'),
    'token' => env('PUSHINPAY_TOKEN'),
    'webhook_token' => env('PUSHINPAY_WEBHOOK_TOKEN'),
],
Enter fullscreen mode Exit fullscreen mode

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"
  }'
Enter fullscreen mode Exit fullscreen mode

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 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',
]);
Enter fullscreen mode Exit fullscreen mode

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 }}">
Enter fullscreen mode Exit fullscreen mode

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');
Enter fullscreen mode Exit fullscreen mode

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();
    }
}
Enter fullscreen mode Exit fullscreen mode

O que esse código resolve:

  • Requisição falsa. Sem o x-pushinpay-token certo, 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 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 do webhook validado. A decisão sai do status do aviso, depois de conferir o header e localizar o pedido pelo id da transação, sem chamada extra à API.
  • 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 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"
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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:

  • 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 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 .env ainda 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-token comparado com hash_equals ao 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_id salvo no pedido.
  • [ ] Aviso visível, antes do pagamento, de que a PushinPay é só a processadora de pagamentos.
  • [ ] Alerta para pedidos parados em created e botão "Já paguei" com no máximo 1 consulta por minuto na conta inteira.
  • [ ] Token de saque separado, se houver saque.
  • [ ] PUSHINPAY_BASE_URL apontando para https://api.pushinpay.com.br, token de produção e PUSHINPAY_WEBHOOK_TOKEN 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

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.