Instalação

Passo a passo completo: registre um tenant, instale o plugin DHRU e envie um pagamento de teste.

Pré-requisitos

• Uma instalação funcional do DHRU Fusion (qualquer versão recente de PHP suportada pelo próprio DHRU).
• Acesso SSH ou painel para colocar dois arquivos PHP em modules/gateways/ e modules/gateways/callback/.
• Uma URL HTTPS publicamente acessível para sua instância DHRU (o TriaPay envia webhooks assinados para ela).
• Uma conta de tenant no TriaPay (registre-se aqui).

1. Crie seu tenant

Registre-se em /register com nome de usuário, e-mail e uma senha de pelo menos 12 caracteres. Verifique seu e-mail pelo link que enviamos. Um administrador então ativa seu tenant, normalmente dentro de um dia útil. Você recebe um segundo e-mail quando a ativação é concluída.

2. Gere as credenciais de API

Faça login. Abra a página Integration. A aba Webhook & API entrega três coisas:

• Webhook URL — onde o TriaPay faz POST dos eventos de crédito. Defina como o caminho de callback do seu DHRU: https://yourdhru.com/modules/gateways/callback/triapay.php. Se seu DHRU está em um subcaminho, prefixe: https://yourdomain.com/dhru/modules/gateways/callback/triapay.php.
• API key — bearer token que seu plugin DHRU usa para criar ordens. Clique em Rotate para gerar. Exibido só uma vez, copie imediatamente.
• Webhook secret — chave HMAC-SHA256 que seu plugin usa para verificar assinaturas de webhook. Clique em Rotate para gerar. Exibido só uma vez.

3. Instale o plugin DHRU

O plugin vem como dois arquivos PHP, ambos baixáveis pela aba Webhook & API:

Download	Coloque em
triapay.php (gateway)	<dhru-root>/modules/gateways/triapay.php
triapay-callback.php (callback, renomeie para triapay.php)	<dhru-root>/modules/gateways/callback/triapay.php

O arquivo de callback é renomeado na instalação porque o DHRU espera que o callback compartilhe o basename do gateway. Distribuímos o download com nome diferente apenas para manter os dois arquivos distinguíveis no diretório plano /downloads/ do TriaPay.

3a. Whitelist do callback em `.htaccess`

O arquivo modules/gateways/callback/.htaccess do DHRU nega acesso por padrão e autoriza callbacks via regex FilesMatch. Adicione |^triapay\.php a essa lista para que os webhooks do TriaPay possam atingir o callback:

<FilesMatch "^wombi\.php|^gourlio\.php|...|^tripay\.php|^triapay\.php">
    Order Allow,Deny
    Allow from all
</FilesMatch>

Sem essa edição, seu DHRU retorna 403 Forbidden em todas as entregas de webhook e os pedidos nunca passam de confirmed. Não é necessário recarregar o Apache — alterações em .htaccess valem na próxima requisição.

3b. Configure o gateway no DHRU

Depois de fazer o upload, abra o admin do DHRU → Settings → Payment Gateways → TriaPay. Cole estes valores:

• API URL: https://triapay.net/api/v1
• API key: o valor tpk_live_... que você rotacionou no passo 2
• Webhook secret: o valor que você rotacionou no passo 2

Salve.

4. Configure os métodos de recebimento

De volta ao dashboard do TriaPay → Integration:

• Aba Crypto → para cada chain que você quer aceitar, defina o master address para onde os clientes enviarão os fundos. TRC20 aceita só USDT; BEP20 aceita USDT e USDC. Opcionalmente, defina valores mínimo/máximo e taxas em Advanced settings.
• Aba Binance Pay → defina seu Pay ID da Binance mais uma API key + secret da Binance com permissões Read and Pay somente. USDT e USDC são suportados aqui. As credenciais são criptografadas em repouso com AES-256-GCM.

5. Envie um pagamento de teste

No painel do cliente do DHRU, entre como um usuário de teste. Crie um depósito de $1. Escolha USDT TRC20 (o mais rápido de confirmar em testes). Envie o valor exato exibido incluindo o sufixo decimal final (por exemplo, 1.0123 USDT; as casas decimais finais codificam o código de correspondência da ordem; a largura é configurável por método, de 1 a 3 dígitos).

A detecção roda em cadência apertada: os listeners de TRC20 e BEP20 varrem a cada 3 segundos, o Binance Pay a cada 5 segundos. O crédito ponta a ponta normalmente leva de 3 a 7 segundos para cripto e de 5 a 10 segundos para Binance Pay, mais a cauda de confirmação da chain.

Em segundos você deve ver:

1. O status da ordem mudando pending → matched → credited no seu dashboard TriaPay.
2. A fatura do DHRU marcada como paga.
3. O saldo do usuário atualizado.

Se algo travar, confira o Audit log do dashboard para entender o motivo da falha.

Resolução de problemas

Sintoma	Causa provável
Ordem travada em confirmed, nunca chega a credited	Falha na entrega do webhook. Veja no audit log a resposta HTTP do seu DHRU. Confira se a URL do webhook é acessível publicamente, se seu DHRU não está atrás de um basic-auth e se o webhook secret está igual nos dois lados.
Pagamento aparece on-chain mas nenhuma ordem casa	O cliente enviou o valor errado ou omitiu a nota do Binance Pay. Abra Admin → Orphan transactions e vincule manualmente à fatura correta.
Plugin recebe 429 Rate limited	O plugin está chamando /api/v1/orders de forma agressiva. O limite é de 60 ordens por tenant por minuto. A resposta agora inclui o header Retry-After (em segundos); aplique backoff e tente novamente.
401 invalid api key	Ou a API key foi rotacionada e o plugin ainda guarda o valor antigo, ou o prefixo da key não bate. Rotacione de novo e cole novamente.
Verificação da assinatura do webhook falha no DHRU	O body precisa ser hasheado exatamente como recebido (bytes crus, sem reencodar). Confira X-Payment-Sig-Version: a versão 2 assina {timestamp}\n{idempotency}\n{body}, a versão 1 assina apenas o body. O plugin DHRU incluído trata ambos durante a janela de rollover de 30 dias. Rejeite se |now − X-Payment-Timestamp| > 300.

Próximos passos

• API reference — contrato REST para integrações diretas
• Webhook spec — formato completo de payload e verificação de assinatura