API de pagos

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

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

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"

Hosted checkout, H2H y cantidades exactas de criptomonedas

El mismo extremo soporta tres formas de invoice distintas. Elige uno deliberadamente; No mezcles la semántica de la cantidad.

Hosted checkout con la elección del pagador

Envía amount, currency, order_id y url_callback, pero omite to_currency y network. La respuesta contiene result.url; Los campos address, qr y a veces pagador permanecen null hasta que el pagador selecciona una dirección en la página alojada.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Dirección directa H2H invoice

Envía tanto to_currency como network. 2328.io crea la invoice blockchain durante el API call, por lo que una respuesta exitosa puede darse dentro de tu caja sin redirigir al cliente.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Renderiza estos valores exactamente como se devolvió:

• payer_amount y payer_currency — la instrucción de pago;
• network y address — el único destino para este invoice;
• qr — un URI de datos para la misma dirección;
• expires_at — la fecha límite invoice;
• url — un fallback alojado útil cuando no se puede completar el pago personalizado.

Invoice para una cantidad exacta de cripto

Mete la criptomoneda en currency cuando el invoice en sí esté denominado en cripto:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

El valor de criptomoneda solicitado se conserva en payer_currency / payer_amount. El servicio también puede mantener una valoración en USD internamente para los campos de contabilidad y tarifas; no reemplaces la instrucción exacta de criptomoneda con esa valoración. Conserva las cadenas decimales devueltas, incluida la precisión final.

Para una criptomoneda con solo una red compatible, la red puede seleccionarse automáticamente. Todavía se recomienda proporcionar network explícitamente para una integración determinista. Para activos de múltiples redes, como las stablecoins, siempre envíalo.

Idempotency y retries

order_id está limitado al proyecto autenticado merchant y actúa como la clave de creación idempotency. Si ya existe un pago, la API devuelve esa sesión con state: 0.

Algoritmo de creación recomendado:

1. Inserta tu intento de pago local y order_id único en una transacción de base de datos.
2. Envía la solicitud API firmada.
3. Persiste el uuid devuelto y la respuesta completa.
4. Si se pierde el resultado HTTP, retry la solicitud idéntica o consulta /v1/payment/info mediante order_id.
5. Nunca crees un segundo pedido local solo porque la solicitud ascendente haya caducado.

Casos límite de pago

La URL de retorno del navegador es solo de navegación. Un cliente puede abrirla sin pagar, cerrarla después de pagar o reproducirla más tarde. Solo un estado verificado de API/webhook puede liquidar la orden merchant.

Información del pago

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"

Lista de pagos

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"