# Referências

> Códigos de rede, mapeamentos moeda-rede e valores de status de pagamento usados em toda a API da 2328.io.

Esta página lista todos os valores de referência utilizados nas requisições e respostas da API.

## Códigos de rede

Estes códigos são utilizados sempre que houver um campo `network`:

| Código | Rede |
|--------|------|
| `TRX-TRC20` | Tron TRC-20 |
| `BSC-BEP20` | BNB Smart Chain |
| `ETH-ERC20` | Ethereum (ERC-20) |
| `BASE` | Base |
| `AVAX-C` | Avalanche C-Chain |
| `POL-MATIC` | Polygon (Matic) |
| `TON` | TON |
| `BTC` | Bitcoin |
| `LTC` | Litecoin |
| `DASH` | Dash |
| `SOL` | Solana |
| `DOGE` | Dogecoin |
| `ZEC` | Zcash |
| `XRP` | XRP Ledger |
| `XMR` | Monero |

## Mapeamento moeda-rede

Cada moeda está disponível apenas em um subconjunto de redes. Use esta tabela para escolher uma combinação válida:

| Moeda | Redes permitidas |
|-------|------------------|
| `USDT` | TRX-TRC20, BSC-BEP20, ETH-ERC20, BASE, AVAX-C, POL-MATIC, TON, SOL |
| `USDC` | BSC-BEP20, ETH-ERC20, BASE, AVAX-C, POL-MATIC, SOL |
| `BTC` | BTC |
| `ETH` | ETH-ERC20, BASE |
| `BNB` | BSC-BEP20 |
| `TRX` | TRX-TRC20 |
| `LTC` | LTC |
| `DASH` | DASH |
| `GRAM` | TON |
| `AVAX` | AVAX-C |
| `POL` | POL-MATIC |
| `SOL` | SOL |
| `DOGE` | DOGE |
| `ZEC` | ZEC |
| `XRP` | XRP |
| `XMR` | XMR |

`GRAM` é o código de ativo canônico para a moeda nativa TON. As APIs de pagamento, carteira estática e criação de pagamento atualmente aceitam a entrada legada `TON` e a normalizam para `GRAM`; as integrações devem armazenar e manipular o valor canônico retornado pela API. O ativo nativo da Polygon é `POL`, enquanto seu código de rede é `POL-MATIC`. Nunca envie `MATIC` como código de rede.

As direções habilitadas são configuração operacional e podem mudar independentemente deste catálogo. Consulte `/v1/directions` antes de apresentar opções; trate esta tabela como o mapa de códigos válido, não como garantia de que todos os pares estejam atualmente habilitados.

## Status de pagamento

O campo `payment_status` em pagamentos e o filtro de `/v1/payment/list` aceita os seguintes valores:

| Status | Descrição |
|--------|-----------|
| `pending` | Criado, aguardando inicialização |
| `check` | Aguardando pagamento do cliente |
| `paid` | Pago com sucesso |
| `underpaid_check` | Pago a menor (pode ser complementado) |
| `underpaid` | Pago a menor |
| `overpaid` | Pago a maior (creditado) |
| `cancel` | Cancelado / expirado |
| `aml_lock` | Transação bloqueada por AML |

> **INFO:** Ao monitorar um pagamento bem-sucedido, você deve tratar tanto `paid` quanto `overpaid` como estados de sucesso e creditar o pedido do cliente.

### Política de gerenciamento de status

| Status | Cumprir pedido? | Continuar esperando? | Ação operacional |
|--------|----------------|-------------------|--------------------|
| `pending` / `check` | Não | Sim, até o vencimento | Exibir estado pendente e reconciliar normalmente. |
| `underpaid_check` | Não por padrão | Sim, o complemento pode chegar | Armazenar cada txid de forma idempotente e mostrar o fluxo de trabalho de pagamento restante. |
| `paid` | Sim, uma vez | Não | Cumprir atomicamente a partir do evento verificado. |
| `overpaid` | Sim, uma vez | Não | Cumprir e reter quantias excedentes/realizadas de acordo com a política do comerciante. |
| `underpaid` | Específico por produto | Não | Aplicar política explícita de pagamento parcial/revisão manual. |
| `cancel` | Não | Não | Marcar como expirado/cancelado, mas escalar qualquer evidência posterior na blockchain. |
| `aml_lock` | Não | Nenhum cumprimento automático | Revisão de conformidade/suporte; não liberar valor automaticamente. |

Os status descrevem a visão da plataforma sobre o pagamento. Eles não substituem seu estado local de cumprimento. Armazene ambos para que um pedido reembolsado, revisado manualmente ou já cumprido não seja corrompido por um webhook mais antigo.

O filtro de solicitação `/v1/payment/list` atualmente aceita `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid` e `cancel`. Ele não aceita `aml_lock` como filtro, mesmo que um pagamento bloqueado por AML possa ser devolvido por outros endpoints de pagamento.

## Status de saque

O campo `status` em `/v1/payout` e `/v1/payout/status/{uuid}` assume um destes valores:

| Status | Descrição |
|--------|-----------|
| `pending` | Criado, aguardando processamento |
| `completed` | Concluído com sucesso — `txid` está definido |
| `failed` | Erro de envio — veja `error_type` |
| `cancelled` | Cancelado |

## Tipos de erro de saque

Quando um saque tem `status = failed`, o campo `error_type` descreve o motivo:

| Código | Descrição |
|--------|-----------|
| `aml_risk` | Saque bloqueado pelas verificações de risco AML (endereço do destinatário sinalizado como de alto risco) |