Pagos y retiros/Monederos estáticos

Monederos estáticos

Direcciones de depósito permanentes vinculadas a un pedido o usuario específico, ideales para pagos recurrentes y a largo plazo.

Ver como Markdown·llms.txt

Los monederos estáticos son direcciones permanentes para recibir pagos en criptomonedas. Están vinculadas a un order_id específico y son únicas por la combinación de project_id + order_id + currency + network.

Usa monederos estáticos para:

Depósitos recurrentes del mismo usuario
Direcciones de pago a largo plazo mostradas en el perfil del usuario
Flujos de depósitos de alto volumen donde quieres una dirección estable por usuario

Crear monedero estático

POST/v1/static-wallet

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
`currency`	string	sí	Criptomoneda (USDT, BTC, ETH, etc.)
`network`	string	sí	Código de red
`order_id`	string	sí	Tu ID de pedido/usuario (hasta 255 caracteres)
`label`	string	no	Etiqueta del monedero (hasta 255 caracteres)
`url_callback`	string	sí	URL para las notificaciones de webhook
`invite_code`	string	no	Código de referido

Ejemplo de solicitud

JSON

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

Ejemplo de respuesta

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..."
  }
}

Información del monedero

Obtén la información de un monedero estático mediante uuid o address.

POST/v1/static-wallet/info

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
`uuid`	string	sí*	UUID del monedero estático
`address`	string	sí*	Dirección del monedero blockchain

Se requiere al menos uno de uuid o address.

Ejemplo de respuesta

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 — suma de todos los depósitos recibidos por este monedero, en currency.
transactions_count — número de depósitos recibidos hasta ahora.
qr — data URI con código QR codificado en Base64 de la dirección de depósito (siempre presente para los monederos estáticos, la dirección se asigna al crearlos).

Lista de monederos

POST/v1/static-wallet/list

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
`status`	string	no	Filtrar por estado (`active`, `inactive`)
`currency`	string	no	Filtrar por divisa
`network`	string	no	Filtrar por red
`order_id`	string	no	Filtrar por order_id
`page`	int	no	Número de página (por defecto: 1)
`per_page`	int	no	Elementos por página (por defecto: 20, máx.: 100)

Ejemplo de respuesta

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
    }
  }
}

Activar / desactivar monedero

Alterna si un monedero estático acepta nuevos pagos.

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

Solicitud

Ambos endpoints aceptan un único parámetro:

JSON

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

Ejemplo de respuesta

JSON

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

Para enable, status es "active" y message muestra "Static wallet enabled successfully".

Transacciones del monedero

Obtén una lista de todos los depósitos recibidos por un monedero estático.

POST/v1/static-wallet/transactions

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
`uuid`	string	sí	UUID del monedero estático
`date_from`	date	no	Fecha de inicio (YYYY-MM-DD)
`date_to`	date	no	Fecha de fin (YYYY-MM-DD)
`page`	int	no	Número de página (por defecto: 1)
`per_page`	int	no	Elementos por página (por defecto: 15, máx.: 5000)

Ejemplo de respuesta

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 — comisión de la plataforma deducida de este depósito, en currency.
net_amount — monto acreditado al saldo del comerciante después de la comisión.

Webhooks de monedero estático

Cuando se recibe un pago en un monedero estático, el sistema envía un webhook a url_callback.

El formato del webhook para monederos estáticos difiere del de los webhooks de pago habituales. En particular, los webhooks de monedero estático incluyen un campo merchant_amount que deberías usar para acreditar.

Payload del 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"
}

Los webhooks de monedero estático no incluyen url ni expires_at (dado que la dirección es permanente, no una sesión). Sí incluyen exchange_rate y created_at.

Referencia de campos

Campo	Tipo	Descripción
`uuid`	string	UUID de la transacción (factura) de este depósito
`order_id`	string	El `order_id` de tu monedero estático
`amount`	decimal (8 dp)	Monto cripto recibido
`currency`	string	Cripto recibida (coincide con la `currency` del monedero)
`amount_usd`	decimal (8 dp)	Valor en USD al momento de la recepción
`exchange_rate`	decimal	Tipo de cambio cripto / USD utilizado
`payer_currency`	string	Igual que `currency` para los monederos estáticos
`payer_amount`	decimal (8 dp)	Igual que `amount` para los monederos estáticos
`network`	string	Red blockchain
`address`	string	Dirección del monedero estático
`payment_status`	string	Siempre `paid` para los monederos estáticos
`txid`	string	Hash de la transacción en la blockchain
`payment_amount`	decimal (8 dp)	Igual que `amount`
`merchant_amount`	decimal (18 dp)	Monto después de la deducción de comisión — úsalo para acreditar
`created_at`	string (ISO 8601)	Cuándo se recibió el depósito
`sign`	string (hex)	Firma HMAC-SHA256 del payload

Buenas prácticas

order_id único — usa un order_id único para cada usuario o pedido
Idempotencia — verifica txid antes de procesar para evitar acreditaciones duplicadas
Verifica firmas — verifica SIEMPRE la firma sign antes de acreditar fondos
Usa merchant_amount — acredita a los usuarios basándote en merchant_amount, no en payment_amount