API Pagamenti

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

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

Checkout ospitato, H2H e importi esatti di criptovaluta

Lo stesso endpoint supporta tre forme distinte di fattura. Scegline una deliberatamente; non mescolare la loro semantica di importo.

Checkout ospitato con scelta del pagatore

Invia amount, currency, order_id e url_callback, ma ometti to_currency e network. La risposta contiene result.url; address, qr e talvolta i campi del pagatore rimangono null fino a quando il pagatore non seleziona una direzione sulla pagina ospitata.

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

Fattura H2H a indirizzo diretto

Invia sia to_currency che network. 2328.io crea la fattura blockchain durante la chiamata API, quindi una risposta riuscita può essere resa all'interno del tuo checkout senza reindirizzare il cliente.

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

Rendi questi valori esattamente come restituiti:

• payer_amount e payer_currency — l'istruzione di pagamento;
• network e address — l'unica destinazione per questa fattura;
• qr — un URI di dati per lo stesso indirizzo;
• expires_at — la scadenza della fattura;
• url — un utile fallback ospitato quando il checkout personalizzato non può completarsi.

Fattura per un importo preciso di criptovaluta

Metti la criptovaluta in currency quando la fattura stessa è denominata in criptovaluta:

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

Il valore richiesto di criptovaluta è conservato in payer_currency / payer_amount. Il servizio può anche mantenere internamente una valutazione in USD per contabilizzazione e campi di tasso; non sostituire l'istruzione esatta sulla criptovaluta con quella valutazione. Conserva le stringhe decimali restituite, inclusa la precisione finale.

Per una criptovaluta con una sola rete supportata, la rete può essere selezionata automaticamente. Fornire network esplicitamente è comunque consigliato per un'integrazione deterministica. Per asset multi-rete come le stablecoin, invialo sempre.

Idempotenza e tentativi

order_id è limitato al progetto commerciante autenticato e funge da chiave di idempotenza per la creazione. Se un pagamento esiste già, l'API restituisce quella sessione con state: 0.

Algoritmo di creazione raccomandato:

1. Inserisci il tuo tentativo di pagamento locale e l'unico order_id in una singola transazione di database.
2. Invia la richiesta API firmata.
3. Conserva il uuid restituito e la risposta completa.
4. Se il risultato HTTP viene perso, ripeti la stessa richiesta o interroga /v1/payment/info tramite order_id.
5. Non creare mai un secondo ordine locale semplicemente perché la richiesta a monte è scaduta.

Casi limite di pagamento

L'URL di ritorno del browser è solo per la navigazione. Un cliente può aprirlo senza pagare, chiuderlo dopo aver pagato o riaprirlo più tardi. Solo uno stato API/webhook verificato può completare l'ordine del commerciante.

Informazioni sul pagamento

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"

Elenco dei pagamenti

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"