# Como estimar uma integração com gateway de pagamento sem estourar o prazo

> A chamada que cria a cobrança é a menor parte de uma integração de pagamento. Como faço spike, levanto as perguntas certas e entrego a estimativa em faixa com premissas.

Por Lucas Roberto · Carreira · publicado em 2026-10-25 · 10 min de leitura
Versão web: https://lucasroberto.com/blog/como-estimar-uma-integracao-com-gateway-de-pagamento-sem-estourar-o-prazo

Para estimar uma integração com gateway de pagamento sem estourar o prazo, não estime a chamada que cria a cobrança. Estime o que acontece depois dela: webhooks fora de ordem, estorno, conciliação, homologação e as respostas que a documentação não mostra. O caminho que me deu mais previsibilidade tem três partes. Primeiro, um spike curto no sandbox antes de dar qualquer número. Depois, uma estimativa quebrada em fases que entregam valor sozinhas. Por último, um prazo comunicado como faixa, com as premissas escritas.

Já integrei Pagar.me, Stripe, Asaas, Zoop e Pluggy, e o padrão se repete. A demo funciona no primeiro dia e a integração fica pronta semanas depois do previsto. O código raramente é o problema. O que atrasa é o trabalho invisível que ninguém colocou na conta.

## Por que a estimativa de integração com gateway sempre estoura?

Quem estima costuma olhar a documentação e pensar: são três endpoints, criar cobrança, consultar e estornar. Isso é o happy path, o fluxo em que tudo dá certo. Em pagamento ele é a menor fatia do esforço, por alguns motivos.

1. **O estado final chega por webhook, não pela resposta da API.** Um webhook é uma notificação HTTP que o provedor manda para o seu sistema quando algo muda. O Pix confirma depois, o cartão pode ir para análise antifraude e o boleto compensa dias depois. Todo o fluxo assíncrono fica fora da estimativa ingênua.
2. **O sandbox mente por omissão.** O ambiente de teste do provedor aprova tudo rápido, raramente simula timeout e às vezes nem dispara todos os eventos que a produção dispara.
3. **Tem gente fora do seu time no caminho crítico.** Credenciamento, liberação de produção, homologação e aprovação de KYC (verificação de identidade do cliente, como a que a Sumsub faz) dependem do provedor, do jurídico ou do financeiro. Esse tempo não depende de você codar mais rápido.
4. **Dinheiro exige rastro.** Conciliação, auditoria e tratamento de disputa não são opcionais em fintech, e cada um vira trabalho de verdade.

Se a estimativa cobre só o item que você controla, ela nasce errada.

## O que entra numa integração de pagamento além da chamada à API?

Antes de qualquer número, passo por esta tabela. Cada linha é uma pergunta que precisa de resposta ou vira risco explícito na estimativa.

| Item | O que é | Pergunta que preciso responder |
|---|---|---|
| Autenticação | Como o provedor identifica sua aplicação | API key simples, OAuth ou certificado mTLS? Tem rotação? |
| Idempotência | Garantir que repetir a requisição não duplica a operação | O provedor aceita Idempotency-Key? Por quanto tempo guarda? |
| Webhooks | Notificações assíncronas de mudança de status | Tem assinatura HMAC? Chegam fora de ordem? Quantas vezes reenviam? |
| Mapeamento de status | Traduzir os status do provedor para os seus | Quantos status existem e quais transições são possíveis? |
| Estorno | Devolver total ou parcialmente | Estorno parcial existe? É síncrono ou chega por webhook? |
| Conciliação | Bater o extrato do provedor com o seu banco | Existe API de extrato ou arquivo? Em que formato e com que atraso? |
| Split | Dividir o valor entre recebedores | Quem paga a taxa? O que acontece com o split no estorno? |
| Disputas | Chargeback e contestação | Como chega a notificação e qual é o prazo de defesa? |
| Homologação | Validação do provedor antes de liberar produção | Tem roteiro obrigatório? Quanto tempo o provedor leva para responder? |
| Limites | Rate limit e janelas de manutenção | Qual o limite por segundo? Retorna Retry-After? |

Algumas linhas já têm solução pronta se o projeto foi bem desenhado. Se a base segue o que descrevi em [como integrar vários gateways de pagamento no Laravel sem amarrar o domínio a um provedor](/blog/como-integrar-varios-gateways-de-pagamento-no-laravel-sem-amarrar-o-dominio-a-um-provedor), o segundo gateway custa bem menos que o primeiro. Você implementa um adapter e reaproveita o domínio, as filas e a máquina de estados. Essa é uma diferença enorme de estimativa e vale explicitar: o primeiro gateway paga a arquitetura, os seguintes pagam só o adapter.

## Como fazer um spike antes de estimar uma integração de pagamento?

Um spike é uma investigação com tempo fixo e descartável, feita para reduzir incerteza e não para entregar código de produção. Para gateway, separo de um a dois dias e saio com respostas, não com feature. O roteiro:

1. Criar a conta de sandbox e medir quanto tempo isso leva. Se o acesso depende de aprovação comercial, isso já é o primeiro risco do cronograma.
2. Fazer uma cobrança de cada método que o produto vai usar: cartão, Pix e boleto.
3. Expor uma rota que só grava os webhooks brutos, sem processar nada.
4. Forçar os cenários feios: cartão recusado, estorno parcial, cobrança expirada, requisição repetida com a mesma chave.
5. Olhar o que chegou: quantos eventos, em que ordem, com que atraso e com que formato de assinatura.

A rota de captura é deliberadamente burra. O objetivo é ver o que o provedor manda de verdade:

```php
// routes/spike.php (carregado só em ambiente local/staging)
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Route;

Route::post('/spike/webhooks/{provider}', function (Request $request, string $provider) {
    DB::table('spike_webhooks')->insert([
        'provider'    => $provider,
        'headers'     => json_encode($request->headers->all()),
        'payload'     => $request->getContent(),
        'received_at' => now(),
    ]);

    return response()->noContent();
});
```

Guardo o corpo cru com `getContent()` e não com `$request->all()`. A validação de assinatura HMAC é calculada sobre os bytes exatos, e qualquer reserialização quebra a comparação. Com os payloads e headers capturados, valido a assinatura no [testador de webhook](/ferramentas/testador-webhook) antes de escrever uma linha de middleware. Assim descubro cedo se o provedor assina o corpo inteiro, se inclui timestamp ou se usa um header fora do padrão.

Depois, uma consulta no PostgreSQL mostra o que importa para a estimativa:

```sql
SELECT payload::jsonb ->> 'type' AS evento,
       count(*)                  AS recebidos,
       min(received_at)          AS primeiro,
       max(received_at)          AS ultimo
FROM spike_webhooks
WHERE provider = 'asaas'
GROUP BY 1
ORDER BY primeiro;
```

Se o mesmo evento aparece mais de uma vez, a idempotência no consumo vira requisito, não detalhe. Se o evento de pagamento confirmado chega antes do evento de criação, preciso tratar ordem. O campo `type` muda de nome conforme o provedor, então ajusto o caminho do JSON. Cada descoberta dessas muda o número que vou dar, e é melhor descobrir no dia dois do que na semana três.

## Quais perguntas fazer ao provedor antes de fechar o prazo?

O spike responde o que o sandbox mostra. O resto vem por escrito do provedor. Mando estas perguntas logo no começo, porque a resposta demora:

1. Qual é o processo para liberar produção e quais documentos são exigidos?
2. Existe roteiro de homologação obrigatório? Quem executa e qual é o prazo típico de resposta?
3. O sandbox dispara os mesmos eventos de webhook que a produção?
4. A política de reenvio de webhook: quantas tentativas, em que intervalo e se existe endpoint para reprocessar manualmente.
5. Como obter o extrato para conciliação: API, arquivo ou só pelo painel?
6. Como funciona o estorno de uma transação com split?
7. Quais são os rate limits por endpoint?
8. Existe janela de manutenção programada e como ela é comunicada?

A pergunta sobre conciliação é a que mais pega. Quando o provedor não tem API de extrato, ou entrega arquivo com dias de atraso, a rotina de [conciliação de pagamentos que bate o extrato do provedor com o seu banco](/blog/conciliacao-de-pagamentos-no-laravel-como-bater-o-extrato-do-provedor-com-o-seu-banco-todo-dia) muda de natureza. Ela deixa de ser um job simples e vira um parser de arquivo com tratamento de divergência. Isso não é ajuste fino. É outra estimativa.

## Como quebrar a estimativa de uma integração de pagamento em fases?

Nunca dou um número único para "integração com o gateway X". Quebro em fases, e cada uma é entregável e útil sozinha. Se o prazo apertar, o negócio decide onde cortar com informação, e não descobre no último dia que nada está pronto.

| Fase | Entrega | O que precisa estar sólido |
|---|---|---|
| 1. Cobrança | Criar cobrança, receber webhook e atualizar status | Idempotency-Key, assinatura validada, consumo idempotente, máquina de estados |
| 2. Estorno | Estorno total e parcial | Reflexo no ledger, status intermediários |
| 3. Conciliação | Rotina diária com relatório de divergências | Fonte do extrato, regras de casamento |
| 4. Avançado | Split, disputas, antecipação | Regras de negócio validadas com financeiro |

A fase 1 não é negociável no que diz respeito a robustez. Não aceito entregar cobrança sem idempotência para ganhar uma semana, porque o custo de errar é cobrar o cliente duas vezes. Já escrevi sobre os detalhes em [como evitar cobrança duplicada com Idempotency-Key quando o gateway dá timeout](/blog/timeout-ao-chamar-o-gateway-de-pagamento-como-evitar-cobranca-duplicada-com-idempotency-key-no-laravel). O ponto aqui é de carreira: o que pode ser cortado é escopo, nunca garantia. Dá para lançar só com Pix e deixar cartão para depois. Não dá para lançar Pix que às vezes credita duas vezes.

Esse é o trade-off que mais preciso defender em conversa com produto. Fatiar por método de pagamento ou por fase é saudável. Fatiar por camada, tipo "faz a cobrança agora e a parte de webhook a gente vê depois", é dívida que vence em produção.

## Como comunicar a estimativa com faixa e premissas?

Um número único passa uma precisão que ninguém tem. Prefiro uma faixa, o cenário provável e o pessimista, acompanhada das premissas que sustentam o otimista. Se uma premissa cai, todo mundo já sabe que o prazo mexe, e ninguém se surpreende.

O formato que costumo mandar é curto:

```text
Integração Gateway X — Fase 1 (Pix + cartão, cobrança e webhook)

Estimativa de desenvolvimento: 8 a 12 dias úteis

Premissas:
- Credenciais de produção liberadas até o fim da semana 1
- Sandbox dispara os mesmos eventos da produção (confirmado no spike)
- Sem roteiro de homologação obrigatório (aguardando resposta por escrito)

Riscos que movem o prazo:
- Homologação obrigatória: +3 a 5 dias, dependendo do provedor
- Webhook sem assinatura: exige consulta de confirmação na API, +2 dias

Fora do escopo desta fase: estorno parcial, split, conciliação
```

Os números do exemplo são ilustrativos. O que importa é a estrutura: a faixa, o que precisa ser verdade para ela valer e o que fica explicitamente de fora. A separação entre tempo de desenvolvimento e tempo de espera também ajuda muito. "Oito dias de código mais o tempo de liberação do provedor" é honesto. "Duas semanas" esconde uma dependência que você não controla.

Alguns critérios que sigo para a faixa:

1. A ponta otimista assume que todas as premissas se confirmam, nunca que tudo vai dar certo de primeira.
2. A ponta pessimista inclui o risco técnico mais provável que o spike revelou.
3. Tempo de espera por terceiro fica em linha separada e nunca entra no meu número de desenvolvimento.
4. Testes de cenário de falha entram no cálculo, não ficam para depois.

## O que fazer quando a estimativa estoura no meio da integração?

Mesmo com spike, às vezes aparece algo que ninguém previu: um evento que só existe em produção, uma regra de split que o financeiro muda no meio do caminho, um rate limit mais baixo que o documentado. O que faço:

1. **Aviso no dia em que descubro, não no dia do prazo.** Uma premissa quebrada é informação, e informação atrasada vira crise.
2. **Conecto o atraso a uma premissa escrita.** "A premissa X caiu, o impacto é Y" é uma conversa técnica. "Atrasou" é uma conversa sobre confiança.
3. **Ofereço opções de escopo, não só de prazo.** Por exemplo: lançar no dia previsto só com Pix, ou esperar mais alguns dias e lançar com cartão também.
4. **Registro o que aprendi sobre o provedor.** A próxima estimativa com o mesmo gateway, ou com um parecido, sai melhor.

O item 4 é o que transforma experiência em senioridade. Mantenho anotações por provedor: como assina webhook, o que o sandbox não simula, quanto tempo levou a liberação, quais status são ambíguos. Com o tempo, o spike de um gateway conhecido vira meia hora de leitura dessas notas.

## Conclusão: o que fazer na próxima vez que pedirem um prazo

Quando alguém perguntar "quanto tempo para integrar o gateway X?", não responda na hora. Peça dois dias. Use o primeiro para criar o sandbox, fazer uma cobrança de cada método e capturar os webhooks brutos. Use o segundo para forçar falhas e mandar as perguntas ao provedor por escrito. Depois entregue a estimativa em fases, com faixa, premissas e o tempo de espera por terceiros separado do tempo de código. E deixe claro desde o início que idempotência, assinatura de webhook e consumo idempotente não entram na lista do que dá para cortar. É isso que separa um prazo que só soa confiante de um prazo que se cumpre.

---

Lucas Roberto é desenvolvedor back-end e fundador da Granpag. Mais textos: https://lucasroberto.com/blog