Pagamenti e prelievi/Payment API

API Pagamenti

Crea e gestisci sessioni di pagamento in criptovaluta con l'API Pagamenti di 2328.io.

L'API Pagamenti consente di creare sessioni di pagamento, reindirizzare i clienti a un checkout ospitato e tracciare lo stato dei pagamenti.

Creare un pagamento

Crea una sessione di pagamento e restituisce un URL a cui il cliente può effettuare il pagamento.

Parametri della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`amount`	decimal	sì	Importo del pagamento nella valuta, es. `100.00`
`currency`	string	sì	Valuta fiat (USD, EUR, RUB, …) o criptovaluta (USDT, TRX, BTC, …)
`order_id`	string	sì	Il tuo ID ordine, es. `ORDER-12345` (fino a 128 caratteri)
`to_currency`	string	no	Criptovaluta preselezionata
`network`	string	no*	Codice di rete (obbligatorio se `to_currency` è impostato o se `currency` è una criptovaluta)
`url_return`	string	no	URL di reindirizzamento dopo il pagamento, es. `https://your-site.com/return`
`url_success`	string	no	Alternativa a `url_return`
`url_callback`	string	no	URL per le notifiche webhook, es. `https://your-site.com/webhook`
`invite_code`	string	no	Codice del referrer
`fee_split`	decimal	no	Quota della commissione del merchant trasferita al pagatore, 0–100 (%). 0 = il merchant paga interamente, 100 = il pagatore paga interamente. Sovrascrive l'impostazione a livello di progetto. Esempio: `30` (il pagatore copre il 30% della commissione).
`price_markup`	decimal	no	Maggiorazione o sconto sull'importo della fattura, da −99 a 100 (%). Sovrascrive l'impostazione a livello di progetto. Esempio: `5` (+5%) o `-10` (sconto del 10%).
`description`	string	no	Descrizione opzionale della fattura (max 200 caratteri). Mostrata al pagatore nella pagina di pagamento. Esempio: `Premium plan — Order #12345`.
`ttl_seconds`	int	no	Durata della fattura in secondi, da `300` (5 minuti) a `86400` (24 ore). Trascorso questo periodo la fattura scade e non può più essere pagata. Predefinito: `3600` (1 ora). Esempio: `3600`.

Risposta

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

Reindirizza il cliente a result.url per completare il pagamento.
tg_deeplink — deeplink al bot Telegram per il pagamento tramite Telegram MiniApp.
qr — codice QR codificato in Base64 (data URI) dell'indirizzo di deposito. Presente quando un indirizzo è già assegnato (quando network è impostato insieme a to_currency, o quando currency è una criptovaluta); altrimenti null.
txid, payment_amount — null finché il cliente non paga. Vengono valorizzati una volta che la transazione è rilevata on-chain. Resta in ascolto del webhook payment_status: paid per sapere quando.
exchange_rate — null se la conversione non è ancora applicabile (es. il tasso fiat → crypto non è stato bloccato). Viene valorizzato una volta scelta una valuta del pagatore.

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.

Informazioni sul pagamento

Ottieni lo stato corrente del pagamento tramite uuid o order_id.

Parametri della richiesta

Campo	Tipo	Obbligatorio	Descrizione	Valori
`uuid`	string	sì*	UUID del pagamento (da `result.uuid` alla creazione)
`order_id`	string	sì*	Il tuo ID ordine

È richiesto almeno uno tra uuid e 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.

Elenco dei pagamenti

Ottieni un elenco di tutti i pagamenti con filtri e paginazione.

Parametri della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`status`	string	no	Filtra per stato del pagamento (vedi References)
`date_from`	date	no	Data di inizio (YYYY-MM-DD), es. `2026-01-01`
`date_to`	date	no	Data di fine (YYYY-MM-DD), es. `2026-01-31`
`page`	int	no	Numero di pagina, default `1`
`per_page`	int	no	Elementi per pagina, default `15`, max `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.