Référence de l’API : transferts et chèques

Les méthodes de paiement sortant. Un transfert envoie des fonds depuis le solde de votre application directement vers le portefeuille d’un utilisateur Telegram ; un chèque est un lien à récupérer que vous approvisionnez d’avance. Les conventions (authentification, enveloppe, montants, spend_id) sont sur la page Référence de l’API marchand.

transfer

POST /pay/api/transfer — permission payouts, limite de 30 par minute. Se règle instantanément et atomiquement ; il n’y a pas d’état en attente.

Paramètre	Type	Requis	Signification
user_id	integer	oui	l’identifiant utilisateur Telegram du destinataire. Le destinataire doit déjà être un utilisateur de l’app — un paiement vers un identifiant inconnu renvoie une erreur au lieu d’abandonner des fonds
asset	string	oui	code de l’actif
amount	string	oui	chaîne décimale positive ; également bornée par le minimum et le maximum par transfert de la plateforme (une estimation en équivalent dollar américain aux cours du moment)
spend_id	string	oui	clé d’idempotence, 1 à 64 caractères, unique par paiement
comment	string	non	jusqu’à 1024 caractères, affiché au destinataire
disable_send_notification	boolean	non	true = ne pas notifier le destinataire dans Telegram

Le résultat est l’objet transfert : transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (toujours completed), created_at, completed_at.

Erreurs : 404 user_not_found (le destinataire n’a jamais utilisé l’app), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (hors des bornes par transfert), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, et la paire spend_id 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — permission payouts, limite de 10 par minute. Une extension pour les paiements de masse : jusqu’à 100 transferts en un appel.

Un seul paramètre : items — un tableau où chaque élément est un jeu complet de paramètres de transfer (user_id, asset, amount, spend_id, avec comment et disable_send_notification en option). Les spend_id doivent être uniques au sein du lot, sinon l’appel entier échoue avec 400 duplicate_spend_id avant que rien ne s’exécute.

Les éléments se règlent indépendamment, dans l’ordre — un élément en échec n’annule jamais les autres. L’appel renvoie un HTTP 200 avec ok: true même quand certains éléments ont échoué : vérifiez donc toujours chaque élément :

• succès : {"ok": true, "spend_id": "…", "result": <objet transfert>}
• échec : {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} avec les mêmes noms d’erreur qu’un transfer simple.

Les éléments d’un lot partagent l’espace de noms d’idempotence avec les transferts simples : réessayer le lot entier — ou renvoyer un élément comme transfer simple avec le même spend_id — rejoue au lieu de payer deux fois.

getTransfers

GET /pay/api/getTransfers — permission read. Filtres : asset, transfer_ids (séparés par des virgules), spend_id (correspondance exacte — retrouvez un paiement par votre propre clé), plus offset / count. Renvoie {"items": [transfer, …]}, les plus récents d’abord.

createCheck

POST /pay/api/createCheck — permission checks, limite de 60 par minute. Crée un chèque à usage unique approvisionné depuis le solde de votre application ; n’importe qui ayant le lien — ou seulement l’utilisateur épinglé — peut le récupérer sur son portefeuille. Le montant est bloqué dès la création du chèque (il passe de available à onhold dans getBalance).

Paramètre	Type	Requis	Signification
asset	string	oui	code de l’actif
amount	string	oui	chaîne décimale positive
pin_to_user_id	integer	non	seul cet identifiant utilisateur Telegram peut récupérer
pin_to_username	string	non	seul ce @username peut récupérer (le @ est facultatif ; ignoré quand pin_to_user_id est aussi défini). Le nom d’utilisateur doit appartenir à un utilisateur existant de l’app
spend_id	string	non	clé d’idempotence (extension) — utilisez-en une

Le résultat est l’objet chèque : check_id, hash, asset, amount, amount_minor, bot_check_url (le lien de récupération t.me), status (active / activated), pin_to_user_id, created_at, activated_at. Une récupération déclenche le webhook facultatif check_activated.

Erreurs : 404 unknown_asset, 400 invalid_amount, 404 user_not_found (le nom d’utilisateur épinglé ne correspond à personne), 409 insufficient_funds, et la paire spend_id.

deleteCheck

POST /pay/api/deleteCheck — permission checks. Un seul paramètre : check_id. Annule un chèque non récupéré et rend le montant bloqué au solde de votre application ; renvoie true. Erreurs : 404 check_not_found, 409 check_not_active (déjà récupéré ou supprimé).

getChecks

GET /pay/api/getChecks — permission read. Filtres : asset, check_ids (séparés par des virgules), status (active / activated), plus offset / count. Renvoie {"items": [check, …]}, les plus récents d’abord ; les chèques supprimés ne sont jamais renvoyés.