2328 Documentation

Bem-vindo à documentação da API 2328.io. Esta referência descreve como integrar o processamento de pagamentos com criptomoedas e saques ao seu aplicativo.

Começando

Para iniciar a integração:

1. Crie uma conta de comerciante e um projeto em 2328.io
2. Obtenha seu UUID do projeto e chave de API nas configurações do projeto
3. Gere uma chave de API de pagamento (Payout) separada se você planeja usar saques
4. Leia a seção Autenticação para aprender como assinar requisições
5. Faça sua primeira chamada Criar Pagamento

URL base

Todas as requisições de API em produção usam a seguinte URL base:

https://api.2328.io/api

Todas as requisições devem ser feitas via HTTPS. Requisições sem HTTPS são bloqueadas.

O que você pode fazer

Com a API 2328.io você pode:

• Aceitar pagamentos em cripto — criar sessões de pagamento e redirecionar clientes para um checkout hospedado ou Telegram MiniApp
• Sacar fundos — enviar pagamentos programaticamente do seu saldo de comerciante para qualquer endereço de blockchain
• Verificar saldos — consultar saldos da conta de comerciante por moeda, equivalentes em USD e valores bloqueados por AML
• Usar carteiras estáticas — gerar endereços de depósito permanentes vinculados a um usuário ou pedido
• Buscar taxas de câmbio — obter taxas em tempo real para pares de moedas fiduciárias e cripto
• Receber webhooks — ser notificado instantaneamente quando o status de um pagamento mudar

Limites de taxa

A API permite até 10 requisições por segundo por projeto. Requisições acima do limite recebem uma resposta HTTP 429 Too Many Requests — aguarde e tente novamente.

Escolha o padrão de integração certo

Requisito	Padrão recomendado	Por quê
Deixe o cliente escolher como pagar	Checkout hospedado	Crie um pagamento e redirecione para result.url; a 2328.io apresenta as direções atualmente disponíveis.
Mantenha o cliente dentro do seu próprio checkout	Fatura H2H com endereço direto	Envie to_currency e network ao criar o pagamento; renderize os address, payer_amount e qr retornados.
Cobrar exatamente 25 USDT ou 0.001 BTC	Fatura denominada em cripto	Coloque a criptomoeda em currency e o valor decimal exato em amount.
Dar a cada usuário um endereço de depósito reutilizável	Carteira estática	O endereço é permanente e pode receber muitos depósitos independentes.
Normalizar ativos recebidos em uma moeda de saldo	Conversão automática	Configure regras do projeto no painel e consuma o resultado convert quando a conversão for concluída.
Trocar um saldo de comerciante existente	Conversão manual	Visualize com /v1/convert/price e depois execute com /v1/convert.
Enviar fundos para um endereço de blockchain	Pagamento (Payout)	Use a chave de API de pagamento separada, calcule primeiro e reconcilie o status do pagamento.

Checkout hospedado e H2H são duas apresentações da mesma API de Pagamento. H2H não cria um pagamento mais fraco ou não assinado: o backend ainda cria a fatura, a 2328.io ainda é dona do endereço e do status, e webhooks assinados permanecem autoritativos para liquidação.

Invariantes de integração

Estas regras se aplicam a toda integração em produção:

• Somente backend — mantenha chaves de API fora de navegadores, aplicativos móveis, logs, análises e capturas de tela de suporte.
• Strings decimais — envie e armazene dinheiro como strings. Nunca arredonde criptomoedas ou taxas de câmbio com aritmética de ponto flutuante binária.
• Chaves de idempotência imutáveis — gere order_id antes da primeira requisição e persista a requisição completa com ela. Uma nova tentativa com o mesmo order_id pode retornar o objeto original em vez de aplicar campos alterados.
• Liquidação baseada em webhook — redirecionamentos, polling do cliente, hashes de transação fornecidos por usuários e timeouts de HTTP não são prova de pagamento.
• Verifique, deduplique e depois altere — verifique o HMAC, reivindique um registro de idempotência atomicamente, atualize o pedido/saldo uma vez e retorne HTTP 200 rapidamente.
• Reconciliação — consulte periodicamente o status de pagamentos, carteiras estáticas e saques para que um webhook perdido não deixe divergência permanente.
• Disponibilidade dinâmica — valide pares de moeda/rede com /v1/directions; um ativo suportado ainda pode ter uma direção de depósito ou saque temporariamente desabilitada.
• Política de status explícita — decida como seu produto lida com pagamento parcial, pagamento em excesso, expiração, bloqueio AML, fallback de conversão e timeouts ambíguos do upstream antes de entrar em produção.

Dados recomendados para persistir

Para pagamentos, armazene no mínimo uuid, order_id, o corpo original da requisição, amount, currency, payer_currency, payer_amount, network, address, expires_at, o payment_status mais recente, txid, payment_amount, merchant_amount, o bloco opcional convert e o payload bruto do webhook verificado.

Para carteiras estáticas, mantenha o uuid da carteira, endereço, moeda, rede, referência de cliente/conta, status e URL de callback separadamente dos registros de depósito. Cada depósito precisa de sua própria transação com uuid, txid, status, valor recebido, valor do comerciante e resultado da conversão.