Référence de l’API marchand

Les conventions communes à toutes les méthodes, plus les méthodes de catalogue en lecture seule. Les pages méthode par méthode : factures et remboursements, transferts et chèques, abonnements, webhooks.

L’API est compatible Crypto Bot : une intégration Crypto Bot existante fonctionne après avoir changé seulement l’URL de base et le token. Tout ce qui dépasse ce contrat est marqué extension ci-dessous.

Une spécification OpenAPI 3.1 lisible par machine de toute l’API — chaque méthode, objet, nom d’erreur et webhook — est publiée à côté de ces pages : crypto-pay-openapi.yaml · crypto-pay-openapi.json. Donnez-la à vos générateurs de code, clients d’API ou outils d’IA.

URL de base et authentification

Toutes les méthodes vivent à https://app.tgpaycrypto.com/pay/api/<methodName>.

Authentifiez chaque requête avec le token dans l’en-tête TgPayCrypto-API-Token (Crypto-Pay-API-Token est accepté comme alias de compatibilité ; si les deux sont envoyés, le canonique l’emporte). Un token absent, invalide ou révoqué — ou le token d’une application supprimée — renvoie 401 unauthorized.

Le token a la forme <app_id>:<secret> et n’est affiché qu’une fois, à la création ou au renouvellement ; le serveur n’en stocke que l’empreinte. Voir Démarrer en tant que développeur.

Tokens et permissions

Deux sortes d’identifiants s’authentifient de façon identique :

• Le token principal — accès complet à toutes les méthodes, et la seule clé qui signe les webhooks.
• Les tokens restreints (extension) — jusqu’à 10 vivants par application, créés dans Plus → API marchand sous Tokens restreints, chacun avec un libellé et un sous-ensemble de permissions. En révoquer un est instantané et ne touche pas les autres ; renouveler le token principal ne les touche pas non plus.

Permission	Méthodes qu’elle débloque
(tout token valide)	getMe, getCurrencies, getExchangeRates
read	getBalance, getStats, getInvoices, getChecks, getTransfers, getSubscriptionPlans, getSubscriptions
invoices	createInvoice, deleteInvoice
refunds	refundInvoice
payouts	transfer, transferBatch
checks	createCheck, deleteCheck
subscriptions	createSubscriptionPlan, archiveSubscriptionPlan, cancelSubscription

Les permissions s’additionnent et sont indépendantes — invoices n’implique pas read, donc un serveur qui ne fait que créer des factures peut détenir un token incapable de lire quoi que ce soit. Appeler une méthode que le token ne couvre pas renvoie 403 scope_required. getMe rapporte les scopes du token courant (null pour le token principal) et son token_name, pour que vous puissiez toujours vérifier ce que vous tenez.

Requêtes et réponses

• Les méthodes de lecture sont en GET avec des paramètres d’URL. Les méthodes qui déplacent de l’argent sont uniquement en POST — paramètres en corps JSON, en form-urlencoded ou en paramètres d’URL (le corps l’emporte en cas de conflit) ; multipart/form-data est refusé.
• Chaque réponse est du JSON avec la même enveloppe : succès {"ok": true, "result": …}, erreur {"ok": false, "error": {"code": <statut HTTP>, "name": "<error_name>"}}. Branchez sur error.name — c’est la chaîne stable lisible par machine.
• Un cas limite : une valeur d’URL de type invalide sur une méthode GET (par exemple offset=abc) renvoie un HTTP 422 avec un corps {"detail": …} hors de l’enveloppe. Envoyez des valeurs d’URL bien typées.

Les montants

• Les montants en crypto sont des chaînes décimales en unités de pièce entière ("10.5") — jamais des nombres JSON. Les réponses portent aussi amount_minor (extension) : la valeur entière en unités mineures sous forme de chaîne, parce que les entiers à l’échelle du wei débordent d’un Number JavaScript.
• Les decimals par actif viennent de getCurrencies — pilotez vos calculs de montants à partir de là plutôt que de les coder en dur.
• Les montants en monnaie fiduciaire ont au plus 2 décimales.
• Les taux sont des chaînes à virgule fixe, jamais des nombres.

La pagination

Les méthodes de liste (getInvoices, getChecks, getTransfers, getSubscriptions) prennent offset (défaut 0) et count (défaut 100, maximum 1000 ; getSubscriptions maximum 500) et renvoient {"items": […]}, les plus récents d’abord. Les filtres d’identifiants (invoice_ids, check_ids, transfer_ids) sont des listes d’entiers séparées par des virgules. Les horodatages sont partout des chaînes ISO 8601.

L’idempotence : spend_id

Les méthodes qui déplacent de l’argent prennent une clé spend_id générée par l’appelant (1 à 64 caractères) : requise sur transfer et sur chaque élément de transferBatch, facultative sur createCheck et refundInvoice (extension — utilisez-la quand même). Réessayer avec la même clé et les mêmes paramètres rejoue le résultat d’origine au lieu de déplacer les fonds deux fois : une requête expirée peut donc toujours être réessayée sans risque. La même clé avec des paramètres différents renvoie 409 idempotency_conflict ; un réessai pendant que l’originale s’exécute encore renvoie 409 idempotency_in_progress.

Les limites de débit

Par application, partagées entre tous ses tokens ; un dépassement renvoie 429 rate_limited :

Méthode	Limite
createInvoice, createCheck	60 par minute
refundInvoice, transfer	30 par minute
transferBatch	10 par minute

Les méthodes de lecture ne sont pas limitées en débit. Pendant une maintenance de la plateforme, les méthodes d’écriture renvoient 503 maintenance tandis que les lectures continuent de fonctionner.

Méthodes de catalogue et de compte

getMe

GET /pay/api/getMe — aucun paramètre. Renvoie l’identité de l’application : app_id, name, payment_processing_bot_username, webhook_url, webhook_events (les types de webhook étendus auxquels l’application s’est abonnée), et les champs d’introspection du token scopes / token_name décrits plus haut.

getBalance

GET /pay/api/getBalance — aucun paramètre. Renvoie un tableau avec une ligne par actif pris en charge, même à zéro : currency_code, available (solde dépensable), onhold (fonds bloqués dans vos chèques en cours) et amount_minor.

getCurrencies

GET /pay/api/getCurrencies — aucun paramètre. La liste qui fait foi de ce que l’API prend en charge : les lignes crypto (is_blockchain: true) et les monnaies fiduciaires dans lesquelles les factures peuvent être libellées (is_fiat: true). Chaque ligne porte code, name, decimals et l’indicateur is_stablecoin.

getExchangeRates

GET /pay/api/getExchangeRates — aucun paramètre. Les cotations crypto-vers-fiat : source, target, rate (une chaîne à virgule fixe) et is_valid — false signifie que toute la table est servie depuis un cache obsolète ; traitez ces taux comme purement indicatifs.

getStats

GET /pay/api/getStats — start_at / end_at facultatifs (ISO 8601 ; la fenêtre par défaut est les dernières 24 heures). Renvoie volume (valeur en dollars des factures payées dans la fenêtre), conversion (payées/créées, en pourcentage), unique_users_count, created_invoice_count, paid_invoice_count, et les bornes effectives de la fenêtre. Une date illisible renvoie 400 invalid_date.

Erreurs que toute méthode peut renvoyer

HTTP	error.name	Quand
401	unauthorized	token absent, invalide ou révoqué
403	scope_required	le token n’a pas la permission de la méthode
400	invalid_request	paramètres illisibles ou invalides (POST)
429	rate_limited	limite de débit dépassée
503	maintenance	maintenance de la plateforme (méthodes d’écriture)
500	internal_error	erreur serveur inattendue

Les erreurs propres à chaque méthode sont listées sur sa page.