Guida · PayStars

PayStars API per sviluppatori: il flusso completo per vendere Stars e Premium nel tuo bot

Come funziona l'API REST di PayStars dall'inizio alla fine: X-API-Key, controlli del nome utente, preventivi in USD con max_usd, ordini idempotenti, l'errore 409 price_changed e la verifica del TxId, come piano di integrazione.

Pubblicato: · Aggiornato:

PayStars API per sviluppatori: il flusso completo per vendere Stars e Premium nel tuo bot

Vuoi vendere Telegram Stars e Premium nel tuo bot, negozio o applicazione? La PayStars API ti offre un'unica interfaccia HTTPS e un saldo in USD condiviso con il sito. Invece di ripetere il riferimento dell'API, questo articolo mostra come costruire l'integrazione dall'inizio alla fine.

L'architettura a colpo d'occhio

Il tuo sistema fa tre cose: ricarica il saldo con USDT, richiede un prezzo e crea un ordine. Tutto il resto, compresa la consegna tramite il flusso di acquisto ufficiale di Telegram, avviene dal lato di PayStars.

ParteCosa fa
AccessoIntestazione X-API-Key; le chiavi si creano nel pannello di controllo
SaldoUSD, ricaricato con USDT (TON, BEP20 o TRC20)
PrezzoPrezzo di Fragment × 1,05, arrotondato per eccesso al centesimo
Limite10 richieste al secondo per chiave
TrasparenzaUn TxId pubblico per ogni ordine completato

Fase 1: ricarica il saldo

POST /usd/invoice con un importo e una rete ("ton", "bsc" o "trc20") restituisce un importo esatto valido per 30 minuti. Il minimo è 0,1 USDT.

Fase 2: verifica il destinatario

POST /api/v1/check-username controlla il destinatario e restituisce un token di verifica a breve durata. Questo evita pagamenti verso nomi utente inesistenti: se un cliente sbaglia a digitare, lo scopri prima che venga addebitato qualcosa.

Fase 3: ottieni il prezzo e fissane il tetto

POST /api/v1/usd/quote restituisce il prezzo attuale (usd) e il ricarico (markup_percent: 5). Il prezzo segue il mercato, quindi:

  • richiedi un preventivo aggiornato prima di ogni ordine;
  • passa max_usd uguale all'importo del preventivo;
  • invia sempre currency: "USD", altrimenti si usa la preferenza salvata dell'account.

Fase 4: crea l'ordine

POST /api/v1/stars/buy oppure /api/v1/premium/buy. Ogni richiesta deve includere un'Idempotency-Key, così se la connessione si interrompe e riprovi non vieni addebitato due volte. Salva la chiave insieme all'ID dell'ordine nel database.

Fase 5: monitora lo stato

GET /api/v1/order/{id} e /api/v1/orders forniscono stati e cronologia. La maggior parte degli ordini viene consegnata entro pochi minuti. Un ordine completato riceve un TxId che sia tu sia il cliente potete verificare sul registro pubblico di PayStars.

Gestire correttamente gli errori

  • 409 price_changed significa che il prezzo ha superato max_usd e non è stato addebitato nulla. Richiedi un nuovo preventivo e mostra al cliente il prezzo aggiornato.
  • Limite di frequenza: non superare 10 richieste al secondo; aggiungi una coda o un ritardo progressivo.
  • Nuovi tentativi: riutilizza sempre la stessa Idempotency-Key.

Prima di andare in produzione

  1. Conserva la chiave API in una variabile d'ambiente del server, non nel codice.
  2. Esegui l'intero flusso con un piccolo ordine reale di 50 Stars.
  3. Mostra ai clienti il loro TxId: rafforza la fiducia.

Documentazione completa e guide rapide: PayStars Stars API e prezzi in USD per l'API. Per i pagamenti nel bot, vedi i beni digitali nei bot si pagano solo in Stars.

Domande frequenti

Esiste un ambiente di prova?

Non c'è un ambiente di prova separato; durante l'integrazione testa con piccoli ordini reali (50 Stars).

Quali linguaggi di programmazione funzionano?

Qualsiasi linguaggio in grado di fare richieste HTTPS. Ci sono guide rapide per Python, Node.js e PHP.

Come ricarico il saldo?

Con USDT su TON, BEP20 o TRC20, minimo 0,1 USDT; ogni fattura ha un importo esatto valido per 30 minuti.

Fonti

Acquista Stars e Premium con USD (USDT)

Con chiave API: prezzo Fragment, 0% (sito: 5%).

Inizia