Pagamentos e saques/Carteiras estáticas

Carteiras estáticas

Endereços de depósito permanentes vinculados a um pedido ou usuário específico, ideais para pagamentos recorrentes e de longo prazo.

Ver como Markdown·llms.txt

Carteiras estáticas são endereços permanentes para receber pagamentos em criptomoedas. Elas são vinculadas a um order_id específico e são únicas pela combinação de project_id + order_id + currency + network.

Use carteiras estáticas para:

Depósitos recorrentes do mesmo usuário
Endereços de pagamento de longo prazo exibidos no perfil de um usuário
Fluxos de depósito de alto volume em que se deseja um endereço estável por usuário

Criar carteira estática

POST/v1/static-wallet

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
`currency`	string	sim	Criptomoeda (USDT, BTC, ETH, etc.)
`network`	string	sim	Código da rede
`order_id`	string	sim	Seu ID de pedido/usuário (até 255 caracteres)
`label`	string	não	Rótulo da carteira (até 255 caracteres)
`url_callback`	string	sim	URL para notificações de webhook
`invite_code`	string	não	Código do indicador

Exemplo de requisição

JSON

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

Exemplo de resposta

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Informações da carteira

Obtenha informações da carteira estática por uuid ou address.

POST/v1/static-wallet/info

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
`uuid`	string	sim*	UUID da carteira estática
`address`	string	sim*	Endereço blockchain da carteira

Pelo menos um entre uuid e address é obrigatório.

Exemplo de resposta

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

total_received — soma de todos os depósitos recebidos por esta carteira, em currency.
transactions_count — número de depósitos recebidos até o momento.
qr — data URI em base64 do QR code do endereço de depósito (sempre presente em carteiras estáticas, pois o endereço é atribuído na criação).

Lista de carteiras

POST/v1/static-wallet/list

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
`status`	string	não	Filtrar por status (`active`, `inactive`)
`currency`	string	não	Filtrar por moeda
`network`	string	não	Filtrar por rede
`order_id`	string	não	Filtrar por order_id
`page`	int	não	Número da página (padrão: 1)
`per_page`	int	não	Itens por página (padrão: 20, máx.: 100)

Exemplo de resposta

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

Habilitar / desabilitar carteira

Alterne se uma carteira estática aceita novos pagamentos.

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

Requisição

Ambos os endpoints recebem um único parâmetro:

JSON

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

Exemplo de resposta

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

Para enable, status é "active" e message é "Static wallet enabled successfully".

Transações da carteira

Obtenha a lista de todos os depósitos recebidos por uma carteira estática.

POST/v1/static-wallet/transactions

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
`uuid`	string	sim	UUID da carteira estática
`date_from`	date	não	Data inicial (YYYY-MM-DD)
`date_to`	date	não	Data final (YYYY-MM-DD)
`page`	int	não	Número da página (padrão: 1)
`per_page`	int	não	Itens por página (padrão: 15, máx.: 5000)

Exemplo de resposta

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

fee_amount — taxa da plataforma deduzida deste depósito, em currency.
net_amount — valor creditado no saldo do comerciante após a taxa.

Webhooks de carteiras estáticas

Quando um pagamento é recebido em uma carteira estática, o sistema envia um webhook para url_callback.

O formato do webhook das carteiras estáticas difere dos webhooks de pagamento comuns. Notavelmente, os webhooks de carteira estática incluem um campo merchant_amount que você deve usar para o crédito.

Payload do webhook

JSON

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

Webhooks de carteira estática não incluem url ou expires_at (já que o endereço é permanente, não uma sessão). Eles incluem exchange_rate e created_at.

Referência de campos

Campo	Tipo	Descrição
`uuid`	string	UUID da transação (fatura) deste depósito
`order_id`	string	O `order_id` da sua carteira estática
`amount`	decimal (8 dp)	Valor em cripto recebido
`currency`	string	Cripto recebida (corresponde ao `currency` da carteira)
`amount_usd`	decimal (8 dp)	Valor em USD no momento do recebimento
`exchange_rate`	decimal	Taxa cripto / USD utilizada
`payer_currency`	string	Igual a `currency` para carteiras estáticas
`payer_amount`	decimal (8 dp)	Igual a `amount` para carteiras estáticas
`network`	string	Rede blockchain
`address`	string	Endereço da carteira estática
`payment_status`	string	Sempre `paid` para carteiras estáticas
`txid`	string	Hash da transação na blockchain
`payment_amount`	decimal (8 dp)	Igual a `amount`
`merchant_amount`	decimal (18 dp)	Valor após dedução da taxa — use este para creditar
`created_at`	string (ISO 8601)	Quando o depósito foi recebido
`sign`	string (hex)	Assinatura HMAC-SHA256 do payload

Boas práticas

order_id único — Use um order_id único para cada usuário ou pedido
Idempotência — Verifique txid antes de processar para evitar créditos duplicados
Verifique assinaturas — SEMPRE verifique a assinatura sign antes de creditar fundos
Use merchant_amount — Credite usuários com base em merchant_amount, não em payment_amount