Perguntas frequentes
Integração & API
O que preciso para começar?
Você precisa de uma API Key (da página de gerenciamento, sob Store) e uma URL de callback (um endpoint POST público) para receber webhooks. Depois, chame POST https://api.payerscan.com/payment/crypto para criar uma fatura e redirecione o cliente para url_payment. Veja Início rápido.
Qual é o Base URL da API?
O Base URL oficial da API é https://api.payerscan.com. Todas as requisições da API devem usar HTTPS.
Posso criar uma fatura sem enviar callback_url?
Sim. Mas você não receberá webhooks de completed/expired. Só poderá verificar o status via GET https://api.payerscan.com/invoice/:trans_id (polling).
Qual é o limite de taxa?
- POST /payment/crypto: 5 requisições/segundo, máximo 60 requisições/minuto (por API Key, fallback para IP).
- GET /invoice/:trans_id: 20 requisições/segundo, máximo 200 requisições/minuto.
Exceder o limite → HTTP 429, com retry_after_seconds no body. Veja Limites de taxa.
O que é request_id e como funciona a idempotência?
request_id é um campo opcional que você inclui ao criar uma fatura — geralmente seu ID de pedido interno (por exemplo: "ORDER-12345") ou uma string aleatória única que só o seu backend e o PayerScan conhecem.
Por que usar? Se o seu servidor travar ou der timeout durante a requisição, você pode retentá-la com segurança usando o mesmo request_id. A API garante que nenhuma fatura duplicada será criada — em vez disso, retorna a fatura existente com "idempotent": true na resposta.
Associar webhooks a pedidos: O request_id também é incluído nos callbacks webhook (completed / expired), permitindo que seu backend identifique a qual fatura (transação, pedido) o pagamento pertence.
Sem request_id: Cada POST cria uma nova fatura, mesmo que o body seja idêntico. Você corre o risco de criar faturas duplicadas para o mesmo pedido ao retentar.
Em qual moeda é o amount?
O campo amount é sempre em USD (dólares americanos). O sistema converte automaticamente para o valor correspondente em criptomoeda com base na taxa de câmbio em tempo real no momento do pagamento.
Nota: A taxa de câmbio é obtida de uma das quatro fontes — Binance, Coinbase, CoinGecko ou CoinMarketCap — selecionada pelo cliente na página de pagamento.
Quais são os limites de amount?
O amount da fatura (em USD) deve ser um número positivo e não pode exceder 1.000.000. Valores podem ser enviados como string ou número.
O que são completed_url e expired_url?
São URLs de redirecionamento opcionais para o navegador do cliente:
completed_url— o cliente é redirecionado aqui após pagamento bem-sucedido.expired_url— o cliente é redirecionado aqui se a fatura expirar.
São apenas para redirecionamento frontend e não substituem o webhook callback_url.
Pagamentos & Confirmação
O que acontece se o cliente envia o valor errado?
O sistema só confirma quando a transação blockchain corresponde exatamente ao valor (token_amount), endereço correto e dentro da janela de tempo. Enviar muito pouco ou muito não será considerado pagamento bem-sucedido; a fatura pode expirar ou o cliente precisa criar uma nova.
Quanto tempo leva a confirmação?
Geralmente alguns segundos a alguns minutos, dependendo da rede e método:
- EVM (BSC, ETH, Polygon, ...): 3-15 segundos
- Tron (TRC20): 3-5 segundos
- Depósitos via exchange (Binance, OKX, Bybit, ...): Quase instantâneo
- Binance Pay: Quase instantâneo
Quando uma transação correspondente é encontrada, o sistema atualiza a fatura e envia o webhook imediatamente.
Quando uma fatura expira?
Por padrão, conforme configuração do Store (ex.: 15 minutos). Ao criar a fatura, a resposta inclui expires_in_minutes. Após esse tempo, a fatura muda para expired e (se callback_url foi fornecido) você recebe um webhook com status: "expired".
Quais são os possíveis status de uma fatura?
| Status | Descrição |
|---|---|
waiting | Fatura criada, aguardando pagamento do cliente. |
completed | Pagamento confirmado na blockchain. |
expired | Fatura expirada sem receber pagamento. |
Posso cancelar uma fatura?
Não. Faturas não podem ser canceladas via API. Elas expiram automaticamente após o tempo configurado (expires_in_minutes). Se o cliente não pagar, deixe expirar.
Webhook
Quais eventos disparam um webhook?
O sistema envia webhooks para dois eventos:
- completed — quando um pagamento correspondente é confirmado na blockchain.
- expired — quando a fatura expira sem receber pagamento.
Qual é o timeout do webhook?
10 segundos. Se o servidor do comerciante não retornar HTTP 2xx nesse tempo, a requisição é considerada falha e será retentada.
Preciso retornar um body específico?
Não. Basta retornar um status HTTP 2xx (ex.: 200 OK). O body é livre (pode ser vazio ou "OK").
Webhooks são retentados em caso de falha?
Sim. Em caso de erro ou timeout, o sistema retenta neste cronograma: 10s → 30s → 30s → 60s → 60s (máximo 5 tentativas). Garanta que seu endpoint trate de forma idempotente (chamar com o mesmo trans_id várias vezes é seguro).
Erros & Solução de problemas
O que significa NO_PAYMENT_METHOD?
Seu Store não tem método de pagamento configurado. Vá ao gerenciamento do Store → adicione pelo menos um endereço de carteira ou conecte uma plataforma de câmbio antes de criar faturas.
O que significa INSUFFICIENT_BALANCE?
O saldo da sua conta é insuficiente para cobrir a taxa de serviço dessa fatura. A taxa é calculada com base no amount (USD) da fatura com a taxa de serviço aplicável à sua conta (descontos podem reduzir a taxa). Recarregue no Dashboard e tente novamente. Verifique o campo details na resposta de erro para o valor exato em falta.
Nota: Durante o período de teste gratuito (primeiros 7 dias),
INSUFFICIENT_BALANCEnão aparecerá — todas as taxas de serviço são isentas.
O que é INVALID_MERCHANT_ID?
O merchant_id no body não corresponde ao Store da API Key sendo usada. Verifique o merchant_id no gerenciamento do Store e envie o correto na requisição.
Consulta de fatura retorna 404?
Causas possíveis: (1) trans_id errado, (2) fatura pertence a outro Store (API Key diferente), ou (3) não existe. Verifique o trans_id e a API Key.
Métodos de pagamento
Quais métodos de pagamento o sistema suporta?
PayerScan suporta vários métodos de pagamento:
- Carteiras on-chain: EVM (BSC, Ethereum, Polygon, Base, Arbitrum), Tron (TRC20), Solana
- Plataformas de câmbio: Binance Pay, Binance Deposit, OKX, Bybit, MEXC, Gate.io, Bitget, Upbit, Bitkub
Veja Redes & Tokens para a lista completa.
Como funciona o Binance Pay?
Binance Pay permite que clientes paguem via Binance — sem taxas de gas, confirmação instantânea. Comerciantes precisam configurar Binance API Key e Secret Key na página de gerenciamento.
O que precisa ser configurado para plataformas de câmbio?
- Crie uma API Key na exchange (ative as permissões necessárias)
- Na página de gerenciamento → configure API Key, Secret Key e ID da plataforma para o Store
Detalhes: Configuração Binance Pay.
Segurança
A API Key deve ser enviada do frontend?
Não. A API Key deve ser usada apenas no servidor (backend do comerciante). Chame POST /payment/crypto e GET /invoice do servidor; o frontend recebe apenas url_payment para redirecionamento e não precisa da API Key.
A URL de callback precisa de autenticação?
Recomendado: verifique merchant_id ou trans_id com dados internos para garantir que a requisição é legítima. Use HTTPS para prevenir escutas.
Posso ter múltiplos Stores?
Sim. Cada Store tem sua própria API Key, merchant_id, métodos de pagamento e configurações. Você pode criar múltiplos Stores para separar diferentes negócios ou ambientes (por exemplo, produção vs. teste).