Informações gerais

Bem-vindo à documentação da API da 2328.io. Esta referência descreve como integrar o processamento de pagamentos e saques em criptomoedas em sua aplicação.

Primeiros passos

Para começar a integração:

1. Crie uma conta de comerciante e um projeto em 2328.io
2. Obtenha o UUID do projeto e a API key nas configurações do projeto
3. Gere uma Payout API key separada caso pretenda usar saques
4. Leia a seção Authentication para aprender a assinar requisições
5. Faça sua primeira chamada de Create Payment

URL base

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

https://api.2328.io/api

O que você pode fazer

Com a API da 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 saques programaticamente do saldo do comerciante para qualquer endereço blockchain
• Consultar saldos — veja os saldos das contas do 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
• Consultar taxas de câmbio — obter taxas em tempo real para pares de moedas fiduciárias e criptomoedas
• Receber webhooks — ser notificado instantaneamente quando o status de um pagamento muda

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 correto

Invariantes de integração

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

• Backend only — mantenha as chaves de API fora de navegadores, aplicativos móveis, logs, análises e capturas de tela de suporte.
• Decimal strings — envie e armazene dinheiro como strings. Nunca arredonde criptomoedas ou taxas de câmbio usando aritmética de ponto flutuante binária.
• Immutable idempotency keys — gere order_id antes da primeira solicitação e persista a solicitação completa com ele. Uma nova tentativa com o mesmo order_id pode retornar o objeto original em vez de aplicar campos alterados.
• Webhook-first settlement — redirecionamentos, polling do cliente, hashes de transação fornecidos por usuários e timeouts HTTP não são prova de pagamento.
• Verify, deduplicate, then mutate — verifique o HMAC, reivindique um registro de idempotência de forma atômica, atualize o pedido/saldo uma vez e retorne HTTP 200 rapidamente.
• Reconciliation — consulte periodicamente o status de pagamento, carteira estática e pagamento para que um webhook perdido não possa deixar um desacordo permanente.
• Dynamic availability — valide pares de moeda/rede com /v1/directions; um ativo suportado ainda pode ter temporariamente uma das direções de depósito ou retirada desativada.
• Explicit status policy — decida como seu produto lida com pagamento parcial, pagamento em excesso, expiração, bloqueio AML, fallback de conversão e timeouts ambíguos de upstream antes de entrar em operação.

Dados recomendados para persistir

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

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