Como Ter um IP Estático para Gateways de Pagamento Brasileiros (Pagar.me, Asaas, DigitoPay)

Read this article in English

Se as suas cobranças ou pagamentos PIX estão falhando com um 401 dizendo que o IP de origem não está autorizado, ou se a sua Edge Function no Supabase recebe erros de conexão recusada ao chamar o provedor de pagamento, a causa quase sempre é uma allowlist de IPs. Os gateways brasileiros, regulados pelo Banco Central, restringem o acesso à API a endereços previamente cadastrados, e a sua plataforma de nuvem não te dá um endereço fixo para cadastrar.

Os Gateways Brasileiros Recusam Requisições de IPs Não Autorizados

Para reduzir fraudes e cumprir suas obrigações regulatórias, os principais provedores de pagamento brasileiros permitem restringir o acesso à API a uma lista de endereços de IP aprovados. Depois que você ativa esse recurso, qualquer requisição vinda de um endereço fora da lista é recusada. No Pagar.me, a recusa é um HTTP 401 informando que o IP de origem não está autorizado a realizar a operação. Em outros gateways, pode aparecer como uma conexão recusada antes de qualquer resposta. De um jeito ou de outro, o gateway está aplicando a sua allowlist, e a solução é fornecer um IP que não muda.

Isso Afeta Mais as Funções Serverless e Edge Functions

O Supabase Edge Functions, o Replit e o AWS Lambda atribuem um IP de saída diferente de forma rotativa, às vezes a cada invocação. Então, mesmo depois de autorizar um endereço, a próxima requisição sai de outro e é recusada. Esse é exatamente o padrão por trás dos erros de conexão recusada quando uma Edge Function do Supabase chama uma API de pagamento brasileira. Não existe um único endereço que você possa cadastrar e que continue válido, e é essa lacuna que um proxy de IP estático resolve. Para a configuração específica da plataforma, veja o guia de IP estático para Supabase Edge Functions.

Como Funciona a Allowlist de Cada Gateway

Pagar.me. O Pagar.me oferece uma IP Allowlist que você gerencia pelo painel. Ela define quais endereços podem enviar requisições transacionais para a sua loja. Uma vez configurada, qualquer endereço fora da lista é bloqueado, e a API retorna um 401 indicando o IP não autorizado.

Asaas. O Asaas chama isso de Whitelist de IPs, em Integrações e Mecanismos de Segurança. Qualquer requisição de um endereço fora da lista é recusada. E o Asaas tem um detalhe que importa muito para quem faz pagamentos: por padrão, toda solicitação de saque feita via API vira um Evento Crítico, que fica pendente aguardando aprovação manual pela interface web ou pelo aplicativo. Você pode configurar a sua Whitelist de IPs para isentar origens confiáveis dessa aprovação manual. Ou seja, para automatizar saques em alto volume, um IP estático cadastrado faz dois trabalhos: satisfaz a allowlist e libera os seus saques sem aprovação manual.

DigitoPay. A API de recebimento e pagamento PIX da DigitoPay é uma escolha comum para empresas brasileiras que automatizam cobranças e pagamentos. Apps que se conectam a ela a partir de IPs rotativos de nuvem batem na mesma parede, e um IP estático cadastrado mantém a conexão estável conforme o volume de requisições cresce.

Nem todo gateway brasileiro usa allowlist de IP, então confira o modelo de segurança do seu provedor antes de assumir que essa é a sua solução. Alguns, como a Efí, autenticam com certificados mTLS em vez de IP. Outros, como o Mercado Pago, publicam os próprios endereços de IP para você liberar do seu lado para webhooks de entrada, o que é o caminho inverso. A abordagem de IP estático deste artigo se aplica a gateways que restringem as suas requisições de saída por IP de origem.

A QuotaGuard Te Dá Dois IPs Estáticos para Cadastrar

A QuotaGuard fornece dois endereços de IP fixos que pertencem à sua conta e nunca mudam. Você roteia o seu tráfego de pagamento pela QuotaGuard, adiciona os dois endereços à allowlist de cada gateway, e todas as requisições passam a sair de um deles, não importa como a sua plataforma rotacione por baixo. Cadastre os dois, porque a QuotaGuard faz balanceamento de carga entre o par e qualquer um deles pode atender uma requisição.

Use o Shield para Dados de Pagamento

Para uma integração de pagamento, use o QuotaGuard Shield. Os payloads PIX carregam dados financeiros e identificadores pessoais como CPF e CNPJ, e o Shield é a escolha indicada para esse tipo de dado, porque a conexão entre o seu app e o proxy também é criptografada, então suas credenciais e seus dados de pagamento nunca ficam expostos nesse trecho. O QuotaGuard Static também funciona e não descriptografa o seu tráfego HTTPS de saída, já que o transporta por um túnel CONNECT, mas para cargas de pagamento sob qualquer revisão de conformidade, o Shield é a escolha certa.

Como Configurar

Guarde a string de conexão da QuotaGuard como uma variável de ambiente no host do seu app, junto das chaves de API do gateway, e depois roteie suas chamadas de pagamento por ela. Copie a string de conexão exata do seu painel da QuotaGuard.

QUOTAGUARDSHIELD_URL="sua string de conexao Shield do painel da QuotaGuard"

Em Python com a biblioteca requests, anexe o proxy à chamada que vai ao seu gateway. O endpoint e o corpo da requisição vêm da documentação da API do seu gateway; o que o proxy muda é apenas o IP de onde a requisição sai.

import os, requests
 
proxies = {
    "http": os.environ["QUOTAGUARDSHIELD_URL"],
    "https": os.environ["QUOTAGUARDSHIELD_URL"],
}
 
# Exemplo: uma requisicao a API do seu gateway, roteada pelos seus IPs estaticos.
# Substitua a URL e o payload pelo endpoint de cobranca ou pagamento do seu gateway.
resp = requests.post(
    "https://api.asaas.com/v3/payments",
    headers={"access_token": os.environ["ASAAS_API_KEY"], "Content-Type": "application/json"},
    json={"billingType": "PIX", "customer": "cus_000000000000", "value": 100.0, "dueDate": "2026-07-01"},
    proxies=proxies,
)
print(resp.status_code)

No Supabase Edge Functions, o runtime Deno suporta um proxy SOCKS5 nativamente, que é a forma mais limpa de rotear as chamadas de saída de uma Edge Function. O guia do Supabase linkado acima cobre essa configuração. Em qualquer plataforma, depois de configurar o proxy, roteie uma requisição para https://ip.quotaguard.com por ele e confirme que o endereço bate com um dos dois IPs estáticos do seu painel. Depois, adicione os dois à allowlist do seu gateway.

O QuotaGuard Shield Custa a Partir de $29/Mês

O Shield é o produto indicado para integrações de pagamento, com banda inclusa e sem taxas de excedente por GB. Os planos começam em $29 por mês, e a maioria das cargas de pagamento cabe nos planos de entrada. O plano Enterprise adiciona IPs dedicados caso a allowlist do seu gateway ou a sua postura de conformidade trate endereços compartilhados como risco. Se você também tem tráfego que não é de pagamento e precisa de IP estático, o QuotaGuard Static começa em $19 por mês. Todos os planos incluem teste, 3 dias nos planos padrão e 7 dias no Enterprise, com cartão de crédito obrigatório. Veja a tabela completa em quotaguard.com/products/pricing.