Riferimento API: trasferimenti e buoni

I metodi per pagare. Un trasferimento manda dei fondi dal saldo della tua app direttamente al portafoglio di un utente Telegram; un buono è un link da riscattare che finanzi in anticipo. Le convenzioni comuni (autenticazione, busta, importi, spend_id) stanno nella pagina Riferimento della Merchant API.

transfer

POST /pay/api/transfer — ambito payouts, limite 30 al minuto. Si chiude all’istante, tutto o niente: non esiste nessuno stato intermedio.

Parametro	Tipo	Obbligatorio	Descrizione
user_id	intero	sì	l’id Telegram di chi riceve. Dev’essere già un utente dell’app: un pagamento verso un id sconosciuto dà errore invece di lasciare i fondi in mezzo al guado
asset	stringa	sì	il codice dell’asset
amount	stringa	sì	stringa decimale positiva; è delimitata anche dal minimo e dal massimo per trasferimento della piattaforma (un controvalore stimato in dollari ai tassi del momento)
spend_id	stringa	sì	chiave di idempotenza, da 1 a 64 caratteri, unica per ogni pagamento
comment	stringa	no	fino a 1024 caratteri, mostrato a chi riceve
disable_send_notification	booleano	no	true = non avvisare chi riceve su Telegram

Il risultato è l’oggetto trasferimento: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (sempre completed), created_at, completed_at.

Errori: 404 user_not_found (chi riceve non ha mai usato l’app), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (fuori dai limiti per trasferimento), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, e la coppia dello spend_id: 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — ambito payouts, limite 10 al minuto. Un’estensione per i pagamenti di massa: fino a 100 trasferimenti in una chiamata sola.

Un parametro solo: items, un array in cui ogni elemento è un set completo di parametri di transfer (user_id, asset, amount, spend_id, più comment e disable_send_notification facoltativi). Gli spend_id devono essere unici dentro il lotto, altrimenti tutta la chiamata fallisce con 400 duplicate_spend_id prima di eseguire qualsiasi cosa.

Gli elementi si chiudono in ordine e in modo indipendente l’uno dall’altro: un elemento che non riesce non annulla mai gli altri. La chiamata restituisce un HTTP 200 con ok: true anche quando alcuni elementi non sono riusciti, quindi controllali sempre uno per uno:

• riuscito: {"ok": true, "spend_id": "…", "result": <oggetto trasferimento>}
• non riuscito: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} con gli stessi nomi d’errore di un transfer singolo.

Gli elementi di un lotto condividono lo spazio dell’idempotenza con i trasferimenti singoli: ritentare tutto il lotto — o rimandare un elemento come transfer singolo con lo stesso spend_id — ripete la risposta invece di pagare due volte.

getTransfers

GET /pay/api/getTransfers — ambito read. Filtri: asset, transfer_ids (separati da virgola), spend_id (corrispondenza esatta: ritrovi un pagamento con la tua stessa chiave), più offset / count. Restituisce {"items": [trasferimento, …]}, dal più recente.

createCheck

POST /pay/api/createCheck — ambito checks, limite 60 al minuto. Crea un buono a riscatto singolo finanziato dal saldo della tua app: può riscattarlo chiunque abbia il link, oppure solo l’utente a cui lo riservi. L’importo viene bloccato nel momento in cui crei il buono (passa da available a onhold in getBalance).

Parametro	Tipo	Obbligatorio	Descrizione
asset	stringa	sì	il codice dell’asset
amount	stringa	sì	stringa decimale positiva
pin_to_user_id	intero	no	può riscattarlo solo questo id Telegram
pin_to_username	stringa	no	può riscattarlo solo questo @username (la @ è facoltativa; ignorato quando c’è anche pin_to_user_id). Lo username deve appartenere a un utente esistente dell’app
spend_id	stringa	no	chiave di idempotenza (estensione): usane una

Il risultato è l’oggetto buono: check_id, hash, asset, amount, amount_minor, bot_check_url (il link t.me per riscattare), status (active / activated), pin_to_user_id, created_at, activated_at. Un riscatto fa partire il webhook facoltativo check_activated.

Errori: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (lo username riservato non corrisponde a nessuno), 409 insufficient_funds, e la coppia dello spend_id.

deleteCheck

POST /pay/api/deleteCheck — ambito checks. Un parametro solo: check_id. Annulla un buono non riscattato e riporta l’importo bloccato sul saldo della tua app; restituisce true. Errori: 404 check_not_found, 409 check_not_active (già riscattato o già eliminato).

getChecks

GET /pay/api/getChecks — ambito read. Filtri: asset, check_ids (separati da virgola), status (active / activated), più offset / count. Restituisce {"items": [buono, …]}, dal più recente; i buoni eliminati non compaiono mai.