Tovanix
Tovanix

Usar pagamentos multichain

Como usar todo o serviço de pagamentos:

  • Duas formas de integração: checkout (configure e envie o link, sem código) e aplicativo com API (seu sistema cria pedidos e recebe as notificações)
  • Dois modelos de custódia: o dinheiro em endereços com custódia da plataforma pode ser sacado depois da consolidação, com a tarifa descontada na consolidação; em endereços de autocustódia, ele vai direto para o seu endereço e a tarifa de cada pagamento é debitada do saldo da conta
  • Configuração do aplicativo: a App Key assina a criação de pedidos, o segredo de notificações assina as notificações, a URL de callback precisa ser https, e o recebimento pode ser por rotação ou 1 para 1
  • A notificação conta como entregue com uma resposta 2xx; as falhas têm até 10 novas tentativas automáticas, e o registro de notificações enviadas permite reenviar
  • Páginas de fundos: pool de endereços, ativos, configuração de consolidação, saques e transferências de fundos, transações e saques via API
  • A precisão do token e o ajuste de recebimento definem os últimos dígitos do valor devido; vários pedidos no mesmo endereço são diferenciados por esses dígitos, então o valor deve ser pago exatamente

O que este serviço faz

Pagamentos multichain é o serviço principal da plataforma: seus clientes pagam em USDT e outras criptomoedas, e o valor chega aos endereços de recebimento da sua conta. Há duas formas de integração; use só uma delas ou as duas ao mesmo tempo.

  • Caixa: a plataforma gera um link de pagamento exclusivo e um QR code. Configure sua marca e parâmetros e envie ao cliente — sem código.
  • Aplicativo e API: crie um aplicativo para obter suas chaves e faça seu sistema criar pedidos e receber webhooks de pagamento. Ideal para quem já tem um sistema para integrar.

Escolha primeiro um modelo de custódia

Há dois tipos de endereço de recebimento: com custódia da plataforma e de autocustódia. O modelo de custódia pertence a cada endereço, e um mesmo aplicativo pode usar os dois tipos ao mesmo tempo. Ele define onde o dinheiro fica, como a tarifa é cobrada e quais recursos estão disponíveis; decida antes de começar a receber.

  • Custódia da plataforma — Os endereços de recebimento são atribuídos pela plataforma. Depois da consolidação, o valor recebido entra em “Disponível para saque (consolidado)”, na página Ativos; a partir daí, você pode sacá-lo para um endereço externo, transferi-lo para o saldo da conta ou sacá-lo pela API.
  • Autocustódia — Importe em Endereços → Endereços de autocustódia os endereços cuja chave privada é sua. O dinheiro vai direto para o seu endereço; a plataforma apenas identifica o recebimento, envia a notificação e registra a operação, sem consolidar — a gestão fica com você.

O dinheiro em endereços de autocustódia não passa pela plataforma e não aparece em “Disponível para saque (consolidado)”; por isso, não pode ser sacado pela plataforma nem pela API de saques. Antes de escolher a autocustódia, confirme que o seu fluxo de pagamentos não depende desses dois caminhos.

Como a tarifa é cobrada

  • Custódia da plataforma — Descontada na consolidação como uma porcentagem do valor consolidado, com uma tarifa mínima própria para cada moeda; o valor restante entra em “Disponível para saque (consolidado)”. A porcentagem é a taxa em vigor na sua conta, que pode ser a taxa padrão, uma taxa exclusiva ou uma taxa escalonada por faixas do valor já consolidado no mês.
  • Autocustódia — Quando cada pedido é recebido, a quantidade de moedas desse pagamento é multiplicada pela taxa, convertida em dólares e debitada do saldo da sua conta, com uma tarifa mínima por pagamento.

A tarifa da autocustódia é debitada do saldo da conta, que pode ficar negativo. Com o saldo abaixo de 0, os aplicativos que recebem em endereços de autocustódia deixam de aceitar novos pedidos — se o cliente tentar criar um pedido nesse momento, a tentativa falha —, mas os pedidos já gerados não são afetados; as notificações de recebimento do modo 1 para 1 também ficam suspensas. Quando uma recarga deixa o saldo acima de 0, tudo volta automaticamente e as notificações suspensas são enviadas.

Consulte as taxas em “Regras de tarifas da plataforma”, em Ativos → Configuração de consolidação: taxa em vigor, taxas escalonadas pelo volume mensal e tarifa mínima de cada token. A linha “Tarifa” nos detalhes do pedido é a base da cobrança para endereços de autocustódia; para endereços com custódia da plataforma, é só um valor de referência, e o valor efetivamente cobrado é o calculado na consolidação.

Criar um aplicativo de pagamento

  • Crie o aplicativo e guarde as credenciais: Em Pagamentos em várias redes → Lista de aplicativos, clique em “Criar aplicativo”; depois da criação, uma janela mostra o App ID e a App Key. Você pode consultar a App Key de novo depois, clicando em “Segredo” na lista de aplicativos. Um aplicativo novo ainda não tem segredo de notificações: na mesma janela, clique em “Redefinir segredo de notificações” para gerar um e configure-o no seu servidor para verificar as assinaturas.
  • Defina as URLs de callback e redirecionamento: A URL de callback recebe as notificações com o resultado do pagamento e precisa ser um endereço https; a URL de redirecionamento é a página para onde o cliente vai depois de pagar. Elas têm finalidades diferentes — não use o mesmo endereço nas duas.
  • Escolha um modo de pagamento: Rotação atribui um endereço do pool a cada pedido criado; 1 para 1 vincula um endereço fixo por cliente e notifica os recebimentos. Ambos podem estar ativos ao mesmo tempo.
  • Escolha as redes e as moedas aceitas: Abra a aba “Configuração de aplicativos” nos detalhes do aplicativo: a lista mostra as redes e os tokens liberados pela plataforma. Marque os que este aplicativo vai aceitar, escolha a moeda fiduciária usada para precificar os pedidos e clique em “Salvar”.

A App Key e o segredo de notificações são credenciais. Ver o segredo de notificações completo, gerá-lo ou redefini-lo exige verificar sua identidade antes; se o aplicativo tiver a API aberta ativada, ver ou redefinir a App Key também exige essa verificação. Depois da redefinição, o valor antigo deixa de funcionar na hora e as integrações em andamento são interrompidas — programe a troca antes de redefinir.

Receber pagamentos pelo caixa

O caixa não exige código: configure e obtenha um link exclusivo e QR code para os clientes. A configuração tem três abas.

  • Parâmetros de pagamento — Aplicativo vinculado, moedas fiduciária e cripto padrão, valor mínimo, janela do pedido, URL de redirecionamento após o pagamento e URL de notificação de pagamento. A janela do pedido é a duração da contagem regressiva na página de pagamento, de 5 a 1440 minutos; quando a contagem termina, o pedido ainda fica guardado por mais 25 minutos para captar pagamentos feitos perto do prazo que ainda estão em confirmação na blockchain. Se você informar uma URL de notificação de pagamento, as notificações vão para ela; se não, vão para a URL de callback do aplicativo vinculado.
  • Identidade da marca — Modelo da página de pagamento (cinco opções — Minimalista moderno, Marca em destaque, Compacto, Cripto nativo e Confiança profissional —, que podem ser trocadas a qualquer momento), logo, nome da marca, cor do tema, slogan e descrição: definem o que o cliente vê ao abrir o checkout.
  • Configurações de exibição — Contatos exibidos ao cliente (e-mail, telefone, Telegram, site oficial), se o cliente pode adicionar uma observação ao pedido e se ele precisa informar um contato, com os tipos de contato aceitos.

Se o aplicativo do caixa tem rotação ativada, a página informa diretamente — essa linha indica de onde vem o endereço de recebimento e não é um erro.

Pedidos, pedidos do caixa e registros de webhook

  • Pedidos: todos os pedidos de recebimento ficam aqui. Os pedidos gerados pelo checkout levam a marca “Checkout” e podem ser filtrados por “Origem do pedido”. Os detalhes do pedido mostram as informações na blockchain, a tarifa desse pagamento e o status da notificação.
  • Pedidos do checkout: lista apenas os pedidos gerados pelo checkout; você pode filtrar por Pendente, Pago, Expirado e Cancelado e copiar o link de pagamento de cada pedido.
  • Registro de notificações enviadas: a requisição, a resposta e o resultado de cada notificação. Comece por aqui ao investigar uma integração — dá para ver se a notificação não foi enviada ou se o seu servidor não a aceitou. Registros bem-sucedidos ou com falha podem ser enviados de novo com “Reenviar”.

Regras de notificação: se o seu servidor responder com qualquer código de status 2xx em até 10 segundos, a notificação conta como entregue — a plataforma não lê o conteúdo da resposta; tempo esgotado, resposta fora de 2xx ou redirecionamento contam como falha. Depois de uma falha, a plataforma tenta de novo após 30 segundos, 1 minuto, 2 minutos e 5 minutos e, em seguida, a cada 10 minutos, com no máximo 10 novas tentativas. Cada notificação traz um notify_id único, que não muda nas novas tentativas automáticas nem em “Reenviar”; use-o para eliminar duplicatas.

Recursos, pool de endereços e pagamentos de saída

Onde o dinheiro fica depende do modelo de custódia; estas páginas cobrem suas diferentes etapas.

  • Pool de endereços — Mostra o total de endereços, quantos estão disponíveis e vinculados e os ativos de cada endereço; você pode adicionar observações visíveis só para você e desvincular um endereço para devolvê-lo ao pool disponível. Endereços com custódia da plataforma podem ser consolidados um a um com “Consolidar”. Endereços de autocustódia são importados pela entrada Endereços de autocustódia; as regras estão na observação abaixo.
  • Ativos — No topo aparecem, separados, o saldo da conta, “Disponível para saque (consolidado)” e “Na blockchain, ainda não consolidado (estimativa)”. Os dois últimos não podem ser somados: o que ainda está na blockchain só pode ser sacado depois de consolidado e descontada a tarifa. A página também dá acesso a Recarregar, Sacar, Transferência de fundos, Faturas da plataforma, Histórico de consolidação e Configuração de consolidação.
  • Configuração de consolidação — Mostra as “Regras de tarifas da plataforma”. Em “Configurações de consolidação automática”, defina um limite por token: ao atingi-lo, a consolidação é feita automaticamente, e o limite não pode ser menor que o mínimo de consolidação da plataforma. Também é possível clicar em “Consolidar agora todos os ativos elegíveis”. Com um limite mais alto, há menos consolidações e a tarifa mínima de cada consolidação é aplicada menos vezes.
  • Saques e transferências de fundos — “Sacar” envia ativos disponíveis para saque a um endereço externo e exige a verificação em duas etapas ativada; a página mostra a tarifa, o saque mínimo e o total debitado de cada moeda. A tarifa é cobrada à parte, e o valor informado chega integralmente. Você também pode criar regras de saque automático, executadas quando a consolidação termina e o limite é atingido. “Transferência de fundos” converte ativos disponíveis para saque em dólares, pela cotação do momento, e os credita no saldo da conta; a operação não pode ser desfeita.
  • Transações — As transações na blockchain de todos os endereços do pool. Cada uma mostra o pedido associado; as que não corresponderam a nenhum pedido aparecem como “Não vinculado”, e as que não geraram pedido aparecem como “Sem pedido”.
  • API de saques — Pagamentos programáticos que usam apenas os ativos de “Disponível para saque (consolidado)”. A “Chave geral” só pode ser ativada depois de configurar a chave pública da sua integração e pelo menos um IP permitido; além disso, a chave de API usada precisa ter “Saques por API” marcado em Gerenciamento de APIs. Você pode definir atraso do saque, modo de tarifa, limite por transação e endereços permitidos; durante o atraso, é possível pausar, cancelar ou processar na hora em “Registros de saques”.

Importar endereços de autocustódia: informe apenas o endereço — a chave privada não é necessária nem aceita. Na importação, use a carteira de cada endereço para assinar como mensagem um texto de verificação exibido na página, comprovando que o endereço é seu; a assinatura não gasta ativos nem autoriza nenhuma transferência, e o texto vale por 15 minutos. As redes aceitas são as exibidas na página, e só endereços TRON e EVM são suportados; importe até 20 por vez e até 100 por rede. Um endereço vinculado a um aplicativo de rotação ou com pedidos ainda não expirados não pode ser excluído; excluí-lo também apaga as transações encontradas nesse endereço.

Configuração de tokens: precisão e ajuste

A configuração de tokens tem dois parâmetros que juntos determinam o valor devido mostrado ao cliente.

  • Precisão: quantidade de casas decimais do valor cripto, configurável de 2 a 10. Recomendam-se seis para USDT / USDC e duas para TRX.
  • Ajuste de recebimento: quando um endereço tem vários pedidos não pagos simultaneamente, o sistema ajusta as últimas casas decimais para diferenciá-los.
  • O ajuste tem tipo e intervalo, que deve caber na precisão — só pode variar dentro das casas decimais permitidas.

É por isso que o valor da página de pagamento deve ser pago exatamente: os últimos dígitos identificam o pedido. Pagar um pouco mais ou menos pode impedir o sistema de identificar a qual pedido pertence a transferência.

Integração com API

A referência completa está na central de documentação para desenvolvedores: esquema de assinatura, exemplos de requisição e resposta, códigos de erro, eventos de notificação e verificação de assinatura. O item Documentação de integração da API, na barra lateral do console, leva direto até lá.

As requisições de criação de pedido são assinadas com a App Key; as notificações que a plataforma envia a você são assinadas com o segredo de notificações — verifique a assinatura no seu servidor. A opção “Permitir outras APIs públicas”, nos detalhes do aplicativo, vem desativada: assim, as credenciais do aplicativo só chamam as APIs de recebimento e de câmbio. Ativada, ela permite consultar outros serviços, mas as APIs que criam pedidos ou fazem cobranças continuam aceitando apenas as chaves de API de Gerenciamento de APIs.

Diagnóstico

  • Um cliente pagou, mas nenhuma notificação chegou — URL de callback errada ou servidor sem resposta adequada — Veja primeiro o Registro de notificações enviadas. Sem registro, confira a URL de callback do aplicativo, que precisa ser https; com registro de falha, confira se o seu servidor respondeu 2xx em até 10 segundos e, depois de corrigir, clique em “Reenviar”. Confirme também que a verificação de assinatura usa o segredo de notificações atual.
  • Uma transferência não correspondeu a um pedido — O valor pago difere do valor exato mostrado — Um mesmo endereço pode ter vários pedidos pendentes, e o sistema os diferencia pelo ajuste nas últimas casas do valor; por isso, pague exatamente o valor mostrado na página, sem nenhuma diferença. Transferências sem correspondência aparecem em Transações como “Não vinculado”.
  • Não é possível obter um endereço de recebimento — O pool não tem endereços livres e a atribuição automática já chegou ao limite; ou os endereços de rotação não incluem nenhum desta rede — 1 para 1: quando o seu pool não tem endereços livres, a plataforma atribui automaticamente até 1000 por rede a cada 24 horas; acima disso, desvincule endereços que você não usa mais ou importe os seus. Rotação: se o aplicativo tem endereços de rotação configurados, só eles são usados — confirme que a lista inclui um endereço desta rede.
  • A API de saques informa que não há saldo — O dinheiro ainda está na blockchain aguardando consolidação, ou foi recebido em um endereço de autocustódia — Confira “Disponível para saque (consolidado)” em Ativos. O que aguarda consolidação pode ser consolidado em Configuração de consolidação, com “Consolidar agora todos os ativos elegíveis”; o dinheiro em endereços de autocustódia não passa pela plataforma e não pode ser sacado pela API.
  • Um aplicativo com endereços de autocustódia não aceita novos pedidos — O saldo da conta está abaixo de 0 — A tarifa da autocustódia é debitada do saldo da conta. Quando uma recarga deixa o saldo acima de 0, o aplicativo volta a funcionar automaticamente e as notificações 1 para 1 suspensas são enviadas.
  • Um endereço 1 para 1 recebeu uma transferência muito pequena e nenhum pedido foi gerado — Recebimentos equivalentes a menos de US$ 0,01 não geram pedido — O dinheiro já chegou ao endereço; só não gera pedido nem notificação. Você encontra a transferência em Transações, marcada como “Sem pedido”.
  • Criar um pedido de recebimento ou vincular um novo endereço é recusado — A conta está restrita ou congelada — Nesse estado, não é possível criar pedidos de recebimento nem vincular novos endereços; os pedidos existentes ainda podem ser consultados e fechados. Fale com o suporte.

Perguntas frequentes

Um cliente pagou, mas meu sistema não recebeu a notificação. O que faço?

Veja primeiro o Registro de notificações enviadas. Se não houver registro, confira se a URL de callback do aplicativo está correta e se é https; se houver registro com falha, o seu servidor não respondeu 2xx em até 10 segundos. Depois de corrigir, clique em “Reenviar” no registro; a plataforma também reenvia automaticamente, seguindo o cronograma de novas tentativas.

Onde vejo a tarifa e quando ela é cobrada?

A taxa em vigor aparece em “Regras de tarifas da plataforma”, em Ativos → Configuração de consolidação. Para endereços com custódia da plataforma, a tarifa é descontada na consolidação; para endereços de autocustódia, ela é debitada do saldo da conta a cada recebimento. Na custódia da plataforma, a “Tarifa” nos detalhes do pedido é só uma referência; o valor efetivo é o calculado na consolidação.

Por que o cliente precisa pagar exatamente o valor mostrado na página?

Porque um mesmo endereço pode ter vários pedidos pendentes ao mesmo tempo, e o sistema os diferencia pelo ajuste nas últimas casas do valor. Se o valor não bater, a transferência pode não ser associada automaticamente ao pedido.

Páginas relacionadas: Central de Ajuda · Guias e perguntas frequentes · Pagamentos com cripto em várias redes · Documentação da API

Carregando…