Como Testar um Gateway de Pagamento em Criptomoeda Antes de Ir ao Ar

Você não pode testar um gateway de pagamento em criptomoeda em um sandbox no Payora, porque o Payora não tem um: sem modo testnet, sem chaves de API em modo de teste, sem faturas falsas. O que você faz em vez disso é inspecionar o checkout real hospedado em /demo, reproduzir um webhook que você mesmo assinou contra seu próprio manipulador, e então enviar um pagamento real de cerca de um dólar para sua própria fatura em uma rede barata. Essa última etapa custa trocados e prova a única coisa que um sandbox nunca poderia.

Por que não há sandbox, e por que isso não é o problema que você pensa que é

Um sandbox é um simulador. Ele permite que você ensaie seu código contra uma ficção que o gateway escreveu. Isso é genuinamente útil para processadores de cartão, onde o adquirente, o motor de risco e os trilhos de liquidação são todos opacos e você não tem outra maneira de entrar.

Cripto é diferente. A parte que quebra em produção quase nunca é a chamada da API. É a cadeia: um pagamento que cai na rede errada, um bloqueio de taxa que expirou enquanto o comprador copiava o endereço, uma política de confirmação que ninguém leu, um endereço que o servidor derivou da chave errada. Um sandbox cria uma fatura paga do nada. Ele não te diz nada sobre nada disso. Pior, ele te diz que tudo está bem, que é a mentira mais cara que um teste pode produzir.

Então, a maneira honesta de testar um gateway de pagamento em criptomoeda é uma escada: tudo o que você pode verificar gratuitamente primeiro, depois um pequeno pagamento real que exercita toda a cadeia de ponta a ponta. Aqui está a ordem em que eu faria isso.

1. Olhe para o checkout real antes de escrever uma linha de código

Abra /demo. Ele gera uma fatura ao vivo no checkout hospedado real, a mesma página que seus compradores verão. Sem conta, sem código. Veja o que realmente acontece: como o seletor de moedas se comporta, como é a janela de bloqueio de taxa, o que o comprador vê enquanto uma transação ainda está não confirmada, o que acontece quando o tempo acaba.

Cinco minutos aqui economizam uma discussão depois, porque a maioria dos bugs de integração começa a vida como um modelo mental errado do fluxo. Leia /docs ao lado e combine cada tela com os campos da fatura por trás dela. Em seguida, crie sua conta em /register e obtenha sua chave de API e api_secret.

2. Exercite seu manipulador de webhook sem gastar nada

Este é o grande. Seu manipulador é o código que transforma "dinheiro chegou" em "cliente recebeu seu item", e é a parte que você pode testar exaustivamente de graça, porque você possui o segredo que assina o webhook. Qualquer coisa que a Payora pode assinar, você pode assinar.

O esquema é HMAC simples. A assinatura é hex(hmac_sha256(timestamp . '.' . rawBody, api_secret)), enviada em X-Payora-Signature, com o mesmo timestamp em X-Payora-Timestamp. O timestamp deve estar dentro de ±120 segundos a partir de agora, e cada entrega carrega um Idempotency-Key cabeçalho que permanece estável em tentativas de reenvio do mesmo evento. Assine o rawbytes do corpo, não um array reencodificado — a reencodificação é a razão clássica pela qual uma assinatura correta falha.

<?php
// Sign a webhook exactly the way Payora signs one, and POST it at your own endpoint.
$secret = 'YOUR_API_SECRET';                          // the secret your handler verifies with
$url    = 'https://yoursite.com/payora-webhook.php';  // your endpoint, on your dev host

$body = json_encode([
    'event'      => 'invoice.paid',
    'invoice_id' => 'inv_local_1',
    'order_id'   => '1001',
    'status'     => 'paid',
    'amount'     => '1.00',
    'currency'   => 'USD',
    'asset'      => 'USDT',
    'network'    => 'tron',
], JSON_UNESCAPED_SLASHES);

$ts  = (string) time();
$sig = hash_hmac('sha256', $ts . '.' . $body, $secret);   // lowercase hex

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,          // send the RAW body you signed
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Payora-Timestamp: ' . $ts,
        'X-Payora-Signature: ' . $sig,
        'Idempotency-Key: whk_local_1',
    ],
]);
$out  = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "$code\n$out\n";

Aponte isso para seu próprio endpoint de desenvolvimento e você terá um gerador de webhook que não custa nada e roda em um loop. O lado da verificação — comparação em tempo constante, verificações de janela, por que você deve ler o fluxo de entrada bruto — é coberto em detalhes em verificação de assinatura de webhook com HMAC-SHA256.

3. Os testes que realmente capturam bugs

Execute cada um deles contra seu manipulador e verifique o banco de dados, não apenas o status HTTP. Os resultados esperados não são notas de rodapé; eles são o teste.

• Assinatura válida → 200, pedido marcado como pago, exatamente uma vez.
• O mesmo webhook entregue duas vezes (mesmo Idempotency-Key) → ainda exatamente um pedido pago. Sem crédito duplo, sem segunda chave de licença, sem segunda etiqueta de envio. Este é o erro real mais comum em integrações de pagamento, e tentativas são normais, não excepcionais.
• Corpo adulterado com a assinatura antiga — mudar amount de 1.00 para 1000.00, manter a assinatura → rejeitado, pedido NÃO pago.
• Assinatura errada ou ausente → rejeitado. Um vazio X-Payora-Signature deve falhar exatamente como um errado.
• Timestamp expirado — defina para dez minutos atrás → rejeitado na janela, embora o HMAC em si seja válido.
• ID de fatura desconhecido ou estrangeiro → rejeitado de forma limpa. Sem erro fatal, sem 500, sem linha meio escrita.
• Seu endpoint retorna 500 → a nova tentativa que se segue não deve ser aplicada duas vezes. Encerre a conexão com o banco de dados no meio do manipulador se você quiser ter certeza.
• Comparação em tempo constante — use hash_equals(), nunca ==. E nunca registre o api_secret, não no nível de depuração, não truncado, não uma vez.

Se todos os oito passarem, seu manipulador está em melhor forma do que a maioria das integrações ao vivo. Agora note o que nenhum deles provou: que o dinheiro pode realmente chegar até você.

4. Um pequeno pagamento real para você mesmo

Agora gaste um dólar. Crie uma fatura através da API ou um link de pagamento de /accept-payments, abra o checkout e pague-a da sua própria carteira, para sua própria fatura, com aproximadamente $1.

Escolha uma rede barata e rápida para que isso custe centavos em vez de dólares: TON (Gram), Tron e Solana confirmam em segundos por uma fração de centavo. Não execute isso na mainnet do Bitcoin, a menos que o Bitcoin seja especificamente o que você está enviando — você vai esperar dez minutos por tentativa e pagar pelo privilégio.

Este único pagamento é o único teste que exercita toda a cadeia: bloqueio de taxa, detecção on-chain, confirmação à política daquele ativo (veja quantas confirmações são seguras), webhook assinado, seu banco de dados. Se funcionar, sua integração funciona. Se não funcionar, a falha é real e específica — que é exatamente o que você quer descobrir em uma terça-feira tranquila e não durante um lançamento.

5. Prove que você pode retirar o dinheiro

Todo mundo ignora isso. É o passo que dói.

Antes de aceitar o pagamento de um único cliente, retire aquele dólar de volta para uma carteira que você controla. Verifique /balance, faça uma retirada ou uma transferência, veja-a chegar. Se você planeja pagar fornecedores ou afiliados, envie um lote através de /mass-payouts com duas linhas e valores triviais, e confirme que a etapa de assinatura offline funciona na sua máquina real com seu material de chave real — não na teoria, na máquina.

Um gateway do qual você pode receber, mas não pode retirar, não é um gateway. É uma armadilha com uma boa página de checkout. Descobrir isso com $1 preso é uma história que você conta depois. Descobrir isso com $40.000 presos é uma tarde muito diferente.

6. Verifique se os endereços derivados são realmente seus

Este é específico para configurações não custodiais e é inegociável. A Payora deriva endereços de recebimento apenas a partir de material de chave pública — seu xPub ou chave pública mestre. Chaves privadas nunca tocam o servidor. Esse é todo o modelo de segurança, e ele carrega um requisito rigoroso: o xPub que você colou deve ser aquele que sua carteira realmente possui.

Então verifique-o de forma independente. Pegue um endereço que o servidor derivou para uma fatura, derive o mesmo índice do seu xPub você mesmo — no software da sua carteira, ou com qualquer biblioteca de carteira HD offline — e compare as strings caractere por caractere. Se elas coincidirem, cada pagamento cai em algum lugar de onde você pode gastar. Se não coincidirem, cada pagamento é perdido, silenciosamente, com um checkout verde e um pedido pago para lhe fazer companhia. O xPub e explicador de carteira HDpassa pela derivação.

Faça isso antes de ir ao vivo. Não depois da primeira reclamação.

A troca, declarada honestamente

Sem sandbox significa que seu primeiro teste real custa um pouco de dinheiro e um pouco de cuidado. Esse é um custo genuíno e não vou fingir o contrário. O que você recebe em troca é um teste que foi verdadeiro. Uma sandbox teria lhe dado um sinal verde para a chamada da API e não teria lhe contado nada sobre o bloqueio de taxa, a política de confirmação, o caminho de retirada, ou se os endereços eram seus — as quatro coisas que realmente decidem se você será pago.

Um dólar, uma tarde e uma lista de verificação superam um simulador que concorda com você.

Pronto para começar? Crie uma conta gratuita em /register, crie sua primeira fatura de /accept-payments, e trabalhe na lista. Toda a escada leva cerca de uma hora e aproximadamente um dólar.