Pagos y retiros/Payment API

API de pagos

Crea y gestiona sesiones de pago en criptomonedas con la API de pagos de 2328.io.

La API de pagos te permite crear sesiones de pago, redirigir a los clientes a un checkout alojado y hacer seguimiento del estado del pago.

Crear pago

Crea una sesión de pago y devuelve una URL para que el cliente realice el pago.

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
`amount`	decimal	sí	Monto del pago en la divisa indicada, p. ej. `100.00`
`currency`	string	sí	Divisa fiat (USD, EUR, RUB, …) o criptomoneda (USDT, TRX, BTC, …)
`order_id`	string	sí	Tu ID de pedido, p. ej. `ORDER-12345` (hasta 128 caracteres)
`to_currency`	string	no	Criptomoneda preseleccionada
`network`	string	no*	Código de red (obligatorio si `to_currency` está definido o si `currency` es una criptomoneda)
`url_return`	string	no	URL de redirección tras el pago, p. ej. `https://your-site.com/return`
`url_success`	string	no	Alternativa a `url_return`
`url_callback`	string	no	URL para las notificaciones de webhook, p. ej. `https://your-site.com/webhook`
`invite_code`	string	no	Código de referido
`fee_split`	decimal	no	Porcentaje de la comisión del comerciante que asume el pagador, 0–100 (%). 0 = el comerciante paga todo, 100 = el pagador paga todo. Sobrescribe el ajuste a nivel de proyecto. Ejemplo: `30` (el pagador cubre el 30 % de la comisión).
`price_markup`	decimal	no	Recargo o descuento sobre el monto facturado, de −99 a 100 (%). Sobrescribe el ajuste a nivel de proyecto. Ejemplo: `5` (+5 %) o `-10` (10 % de descuento).
`description`	string	no	Descripción opcional de la factura (máx. 200 caracteres). Se muestra al pagador en la página de pago. Ejemplo: `Premium plan — Order #12345`.
`ttl_seconds`	int	no	Tiempo de vida de la factura en segundos, de `300` (5 minutos) a `86400` (24 horas). Pasado ese tiempo la factura caduca y ya no puede pagarse. Valor por defecto: `3600` (1 hora). Ejemplo: `3600`.

Respuesta

JSON

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Redirige al cliente a result.url para completar el pago.
tg_deeplink — deeplink del bot de Telegram para pagar a través de Telegram MiniApp.
qr — código QR codificado en Base64 (data URI) de la dirección de depósito. Está presente cuando ya se ha asignado una dirección (cuando network se define junto con to_currency, o cuando currency es una criptomoneda); en caso contrario, es null.
txid, payment_amount — son null hasta que el cliente paga. Se completan una vez que la transacción se detecta en la blockchain. Escucha el webhook con payment_status: paid para enterarte.
exchange_rate — es null cuando la conversión aún no aplica (p. ej., aún no se ha fijado el tipo fiat → cripto). Se completa una vez que se elige una divisa de pago.

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Información del pago

Obtén el estado actual del pago mediante uuid u order_id.

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción	Valores
`uuid`	string	sí*	UUID del pago (de `result.uuid` al crearlo)
`order_id`	string	sí*	Tu ID de pedido

Se requiere al menos uno de uuid u order_id.

RequestPOST/v1/payment/info

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Lista de pagos

Obtén una lista de todos los pagos con filtros y paginación.

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
`status`	string	no	Filtrar por estado del pago (consulta References)
`date_from`	date	no	Fecha de inicio (YYYY-MM-DD), p. ej. `2026-01-01`
`date_to`	date	no	Fecha de fin (YYYY-MM-DD), p. ej. `2026-01-31`
`page`	int	no	Número de página, por defecto `1`
`per_page`	int	no	Elementos por página, por defecto `15`, máximo `5000`

RequestPOST/v1/payment/list

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.