Informazioni Generali

Benvenuto nella documentazione dell'API di 2328.io. Questo riferimento descrive come integrare l'elaborazione dei pagamenti in criptovaluta e i prelievi nella tua applicazione.

Per iniziare

Per avviare l'integrazione:

1. Crea un account merchant e un progetto su 2328.io
2. Ottieni il tuo project UUID e l'API key dalle impostazioni del progetto
3. Genera una Payout API key separata se intendi utilizzare i prelievi
4. Leggi la sezione Authentication per scoprire come firmare le richieste
5. Effettua la tua prima chiamata Create Payment

URL di base

Tutte le richieste API in produzione utilizzano il seguente URL di base:

https://api.2328.io/api

Cosa puoi fare

Con l'API di 2328.io puoi:

• Accettare pagamenti in criptovaluta — creare sessioni di pagamento e reindirizzare i clienti a un checkout ospitato o a una Telegram MiniApp
• Prelevare fondi — inviare prelievi in modo programmatico dal saldo merchant a qualsiasi indirizzo blockchain
• Controllare i saldi — visualizza i saldi degli account merchant per valuta, gli equivalenti in USD e gli importi bloccati per AML
• Utilizzare wallet statici — generare indirizzi di deposito permanenti associati a un utente o a un ordine
• Recuperare i tassi di cambio — ottenere tassi in tempo reale per coppie fiat e crypto
• Ricevere webhook — essere notificato istantaneamente al cambio di stato di un pagamento

Limiti di frequenza

L'API consente fino a 10 richieste al secondo per progetto. Le richieste oltre il limite ricevono una risposta HTTP 429 Too Many Requests — applica un backoff e riprova.

Scegli il giusto modello di integrazione

Invarianti di integrazione

Queste regole si applicano a ogni integrazione di produzione:

• Backend only — tieni le chiavi API fuori dai browser, dalle applicazioni mobili, dai log, dall'analisi e dagli screenshot di supporto.
• Decimal strings — invia e conserva denaro come stringhe. Non arrotondare mai criptovalute o tassi di cambio con l'aritmetica a virgola mobile binaria.
• Immutable idempotency keys — genera order_id prima della prima richiesta e conserva la richiesta completa con esso. Un tentativo di nuovo con lo stesso order_id può restituire l'oggetto originale invece di applicare campi modificati.
• Webhook-first settlement — reindirizzamenti, polling del client, hash di transazioni forniti dagli utenti e timeout HTTP non sono prova di pagamento.
• Verify, deduplicate, then mutate — verifica l'HMAC, richiedi in modo atomico un record di idempotenza, aggiorna l'ordine/saldo una sola volta e restituisci rapidamente HTTP 200.
• Reconciliation — interroga periodicamente lo stato di pagamento, portafoglio statico e pagamento in modo che un webhook perso non possa lasciare disaccordi permanenti.
• Dynamic availability — convalidare le coppie valuta/rete con /v1/directions; un asset supportato può comunque avere temporaneamente disabilitato un senso di deposito o prelievo.
• Explicit status policy — decidere come il tuo prodotto gestisce pagamento parziale, pagamento in eccesso, scadenza, blocco AML, conversione di fallback e timeout ambigui a monte prima del lancio.

Dati consigliati da conservare

Per i pagamenti, memorizzare almeno uuid, order_id, il corpo della richiesta originale, amount, currency, payer_currency, payer_amount, network, address, expires_at, l'ultimo payment_status, txid, payment_amount, merchant_amount, il blocco opzionale convert e il payload webhook verificato grezzo.

Per i portafogli statici, tieni il portafoglio uuid, l'indirizzo, la valuta, la rete, il riferimento cliente/contabile, lo stato e l'URL di callback separati dai record dei depositi. Ogni deposito necessita del proprio uuid, txid, stato, importo ricevuto, importo del commerciante e risultato della conversione.