# Referencias

> Códigos de red, asignaciones divisa-red y valores de estado de pago utilizados en la API de 2328.io.

Esta página enumera todos los valores de referencia utilizados en las solicitudes y respuestas de la API.

## Códigos de red

Estos códigos se utilizan en cualquier campo `network`:

| Código | Red |
|--------|-----|
| `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 |

## Asignación divisa-red

Cada divisa solo está disponible en un subconjunto de redes. Usa esta tabla para elegir una combinación válida:

| Divisa | 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` es el código de activo canónico para la moneda nativa de TON. Las APIs de pago, cartera estática y creación de pagos actualmente aceptan la entrada legada `TON` y la normalizan a `GRAM`; las integraciones deben almacenar y manejar el valor canónico devuelto por la API. El activo nativo de Polygon es `POL`, mientras que su código de red es `POL-MATIC`. Nunca envíe `MATIC` como código de red.

Las direcciones habilitadas son configuración operativa y pueden cambiar independientemente de este catálogo. Consulte `/v1/directions` antes de presentar opciones; trate esta tabla como el mapa de códigos válido, no como una garantía de que cada par esté actualmente habilitado.

## Estados de pago

El campo `payment_status` en los pagos y el filtro de `/v1/payment/list` admite los siguientes valores:

| Estado | Descripción |
|--------|-------------|
| `pending` | Creado, pendiente de inicialización |
| `check` | A la espera del pago del cliente |
| `paid` | Pagado correctamente |
| `underpaid_check` | Pago insuficiente (se puede completar) |
| `underpaid` | Pago insuficiente |
| `overpaid` | Sobrepago (acreditado) |
| `cancel` | Cancelado / expirado |
| `aml_lock` | Transacción bloqueada por AML |

> **INFO:** Cuando esperes un pago exitoso, debes tratar `paid` y `overpaid` como estados exitosos y acreditar el pedido del cliente.

### Política de manejo de estado

| Estado | ¿Cumplir el pedido? | ¿Continuar esperando? | Acción operativa |
|--------|----------------|-------------------|--------------------|
| `pending` / `check` | No | Sí, hasta el vencimiento | Mostrar estado pendiente y reconciliar normalmente. |
| `underpaid_check` | No por defecto | Sí, la recarga puede llegar | Almacenar cada txid de manera idempotente y mostrar el flujo de pago restante. |
| `paid` | Sí, una vez | No | Cumplir de manera atómica a partir del evento verificado. |
| `overpaid` | Sí, una vez | No | Cumplir y retener los montos excedentes/actuales según la política merchant. |
| `underpaid` | Específico del producto | No | Aplicar política explícita de pago parcial/revisión manual. |
| `cancel` | No | No | Marcar como vencido/cancelado, pero escalar cualquier evidencia en la cadena posterior. |
| `aml_lock` | No | Sin cumplimiento automático | Revisión de cumplimiento/soporte; no liberar valor automáticamente. |

Los estados describen la visión de la plataforma sobre el pago. No reemplazan su estado de cumplimiento local. Almacene ambos para que un pedido reembolsado, revisado manualmente o ya cumplido no pueda ser corrompido por un webhook más antiguo.

El filtro de solicitudes `/v1/payment/list` actualmente acepta `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid` y `cancel`. No acepta `aml_lock` como filtro, aunque un pago bloqueado por AML pueda ser devuelto por otros puntos de pago.

## Estados de retiro

El campo `status` en `/v1/payout` y `/v1/payout/status/{uuid}` toma uno de:

| Estado | Descripción |
|--------|-------------|
| `pending` | Creado, pendiente de procesamiento |
| `completed` | Completado correctamente — `txid` está definido |
| `failed` | Error de envío — consulta `error_type` |
| `cancelled` | Cancelado |

## Tipos de error de retiro

Cuando un retiro tiene `status = failed`, el campo `error_type` describe la causa:

| Código | Descripción |
|--------|-------------|
| `aml_risk` | Retiro bloqueado por verificaciones de riesgo AML (la dirección destinataria fue marcada como de alto riesgo) |