Merchant API reference

Wo conventions jo har method mein common hain, aur saath mein read-only catalog methods. Har method ke apne pages: invoices aur refunds, transfers aur checks, subscriptions, webhooks.

Yahan documented methods ke liye API Crypto Bot conventions follow karta hai. Base URL aur token badlein, phir apni integration ke use kiye methods testnet par test karein. Hamaare additions neeche extension se marked hain.

Machine-readable OpenAPI 3.1 spec bhi available hai: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Ise code generators, API clients ya AI tools ko dein, lekin method pages bhi check karein: schema naye extensions se peeche ho sakta hai.

Base URL aur authentication

Sabhi methods https://app.tgpaycrypto.com/pay/api/<methodName> par hain. Testnet par base https://testnet.tgpaycrypto.com/pay/api hai — alag apps aur tokens, aur test funds jinki koi value nahi.

Har request mein token TgPayCrypto-API-Token header mein dein (TgCryptoPay-API-Token, jo 2026-09-07 se pehle ka naam tha, aur Crypto-Pay-API-Token compatibility aliases hain; kai headers hon to canonical header use hota hai). Missing, invalid ya revoked token — ya expired restricted token, deleted app ka token, ya blocked owner ka token — 401 unauthorized deta hai.

Token ka roop <app_id>:<secret> hota hai aur wo ek hi baar dikhta hai — banate waqt ya rotate karte waqt; server sirf uska hash rakhta hai. Dekhein Developer ke taur par shuruaat.

Tokens aur scopes

Do tarah ke credentials bilkul ek hi tarah authenticate karte hain:

• Main token — har method ka poora access aur webhook sign karne ki ekmaatra key.
• Restricted tokens (extension) — har app mein 10 unrevoked tokens tak, expired tokens samet. More → Merchant API mein app chunein, phir Access aur tokens kholein. Restricted tokens mein label aur chune hue scopes ke saath banaayein. Ek revoke karne ka asar turant hota hai aur doosron par nahi padta; main token rotate karne par bhi yeh nahi badalte. Token ki expiry bhi set ho sakti hai; uske baad authentication nahi hota.

Scope	Kaun se methods khulte hain
(koi bhi valid token)	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
webhooks	updateApp

Scopes additive aur ek doosre se alag hain — invoices ka matlab read nahi hai, isliye jo server sirf invoices banata hai wo balances ya payment history ke access ke bina token use kar sakta hai. Jis method ko token cover nahi karta use call karne par 403 scope_required milta hai. getMe maujooda token ke scopes (main token ke liye null) aur token_name batata hai, isliye aap hamesha dekh sakte hain ki aapke paas kya hai.

Payout mode

Scope yeh tay karta hai ki token kaun se methods call kar sakta hai; app ka payout mode yeh tay karta hai ki uska koi bhi token — main token samet — kise pay kar sakta hai. Naya app pehle minute se hi kisi ko bhi pay kar sakta hai; owner More → Merchant API mein app kholkar Payout settings → API ke through payouts se recipients limit kar sakta hai — leak hue token se bachaav ke liye, bilkul daily limit ki tarah. Restriction kam karne par PIN ya biometrics maanga jaata hai; API ise sirf padh sakta hai (getMe → payout_mode).

payout_mode	transfer, transferBatch aur createCheck kya kar sakte hain
any	Kisi bhi user ko pay karna, unknown @username ka payout hold karna, bearer checks banaana — default aur Crypto Bot ka behavior
allowlist	Sirf listed Telegram users ko pay karna. Har pinned ya named check recipient list mein hona chahiye. Doosre recipients, unknown @username aur bearer checks par 403 recipient_not_allowed
off	Koi payout nahi — har payout call par 403 payouts_disabled; invoices, subscriptions, refunds aur webhooks normal kaam karte hain

Agar koi payout reject ho jaaye, to owner ko Telegram par notification milta hai (har app ke liye ghante mein zyada se zyada ek baar) aur wo mode badal sakta hai. Mode ke saath-saath daily payout limit bhi laagu hoti hai. Aap kis cheez ke liye pay kar sakte hain, yeh Merchant API ki terms tay karti hain.

Requests aur responses

• Read methods GET hain aur unke parameters query string mein jaate hain. Paisa move karne wale methods sirf POST hain — parameters JSON body, form-urlencoded, ya query params ki tarah (conflict par body wali value maani jaati hai); multipart/form-data reject hota hai. Kisi aur Content-Type (text/plain ya bina header) wali body ignore hoti hai aur sirf query params padhe jaate hain. Array parameters (transferBatch.items, createCheck.recipients) sirf JSON body mein kaam karte hain.
• API handlers ke responses ek common JSON envelope use karte hain: success {"ok": true, "result": …}, error {"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}. error.name par branch karein — wahi stable machine-readable string hai.
• GET method ki query value galat type ki ho (jaise offset=abc), to request API handler tak pahunchne se pehle reject ho sakti hai. HTTP status check karein; har error response mein upar wala envelope hoga, yeh na maanein. Query values expected type ki bhejein.

Amounts

• Crypto amounts asset ki units mein decimal strings hoti hain ("10.5") — kabhi JSON numbers nahi, requests mein bhi nahi: {"amount": 10.5} par 400 invalid_request milta hai, iski jagah {"amount": "10.5"} bhejein. Yahi baat baaki har string parameter par bhi laagu hai (asset, spend_id, comment, …).
• Agar amount mein asset se zyada decimal places hon, to use reject nahi kiya jaata, asset ki precision tak round kiya jaata hai (beech ki value upar round hoti hai); round hone ke baad zero ho jaane wala amount 400 invalid_amount deta hai.
• Responses ke saath amount_minor bhi aata hai (extension): integer minor-unit value ek string ki tarah, kyunki wei-scale integers JavaScript Number ki exact integer precision se bade ho sakte hain.
• Per-asset decimals getCurrencies se aate hain — amounts ki calculation mein wahi decimals use karein, hardcode na karein.
• Fiat amounts mein zyada se zyada 2 decimal places hote hain.
• Rates fixed-point strings hote hain, kabhi numbers nahi.

Pagination

List methods (getInvoices, getChecks, getTransfers, getSubscriptions) offset (default 0) aur count (default 100, max 1000; getSubscriptions ke liye max 500) lete hain aur {"items": […]} dete hain, sabse naya pehle. ID filters (invoice_ids, check_ids, transfer_ids) comma se alag ki gayi integer lists hain. Har jagah timestamps ISO 8601 strings hain.

Idempotency: spend_id

Paisa move karne wale methods caller ki banayi hui spend_id key lete hain (1–64 characters): transfer par aur har transferBatch item par zaroori, createCheck aur refundInvoice par optional (extension — phir bhi use karein). transfer aur transferBatch items ek hi key space share karte hain. Wahi key aur wahi parameters ke saath retry karne par funds do baar move hone ke bajaay purana result replay hota hai, isliye timeout wali request dobara bhejna hamesha safe hai. Wahi key alag parameters ke saath 409 idempotency_conflict deti hai; original abhi chal hi raha ho aur tab retry karein to 409 idempotency_in_progress milta hai. 4xx error se fail hui request apni key use nahi karti: usi key se retry karne par request dobara chalti hai.

Rate limits

Limits per app laagu hoti hain aur uske sabhi tokens mein shared hoti hain, har method ka counter alag hota hai. Limit paar karne par 429 rate_limited milta hai:

Method	Limit
createInvoice, createCheck	60 per minute
refundInvoice	30 per minute
transfer	30 per minute
transferBatch	10 per minute
updateApp	10 per minute
createSubscriptionPlan	20 per minute

Tokens ya recipients ko guess karne ki koshishon ko rokne ke liye do aur limits hain:

• Failed authentication: ek IP address se ek minute mein missing ya invalid token wali 30 requests ke baad, us address ki har request ko minute khatam hone tak 429 rate_limited milta hai — valid token wali requests ko bhi. Galat configure kiye gaye job ko production traffic wale IP se na chalaayein.
• Unknown recipients: ek app mein ek minute ke andar non-existent user_id ya @username ke 10 lookups ke baad (transfer, transferBatch items, pin_to_username ke saath createCheck), us app ka har recipient lookup minute khatam hone tak 429 rate_limited deta hai.

Extra request limits bhi laagu ho sakti hain. 429 rate_limited par retry se pehle ka delay badhaayein. Platform maintenance ke dauraan write methods 503 maintenance dete hain; reads chalte rahte hain.

Catalog aur account methods

getMe

GET /pay/api/getMe — koi parameter nahi. App ki identity deta hai: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (app ke chune extended webhook types), upar diye token introspection fields scopes / token_name, aur payout_mode (off / allowlist / any), daily_payout_max_usd_cents (0 = owner ki set ki hui limit nahi) aur daily_payout_spent_usd_cents (pichhle 24 ghanton ka spend).

updateApp

POST /pay/api/updateApp — scope webhooks. Optional parameters: name (1–64 characters), webhook_url (public HTTPS URL, zyada se zyada 256 characters; empty string se URL hat jaata hai), aur webhook_events (supported extra event names ki array ya comma-separated list). Empty event list par sirf invoice_paid rehta hai. Response mein getMe wale app fields milte hain.

Errors: 400 invalid_request (name 1–64 characters mein nahi, ya webhook_url public HTTPS address nahi hai ya 256 characters se lamba hai), 400 invalid_name (name link ya @username jaisa hai), 400 app_name_reserved (name mein TgPay Crypto ka naam hai), aur 400 invalid_webhook_events (unknown event name; invoice_paid bhi is list mein nahi dena hai, kyunki uske liye opt-in zaroori nahi).

getBalance

GET /pay/api/getBalance — koi parameter nahi. Har supported asset ki ek row waala array deta hai, zero balance par bhi (band kiya gaya asset tabhi dikhta hai jab tak app ke paas uska balance ho): currency_code, available (kharch karne laayak balance), onhold (unclaimed check funds aur pending @username payouts), aur amount_minor.

getCurrencies

GET /pay/api/getCurrencies — koi parameters nahi. API kya support karta hai uski authoritative list: crypto rows (is_blockchain: true) aur wo fiat currencies jinmein invoices ki price rakhi ja sakti hai (is_fiat: true). Har row mein code, name, decimals aur is_stablecoin flag hota hai.

getExchangeRates

GET /pay/api/getExchangeRates — koi parameter nahi. Crypto-to-fiat quotes: source, target, rate (fixed-point string), is_valid, is_crypto aur is_fiat. In rates ko estimate maanein. is_valid: true se quote current hone ki guarantee nahi milti. Rates na mil paayein to result khaali array ho sakta hai. Actual payment ka hisaab milaane ke liye invoice par record kiye gaye amounts aur rates use karein.

getStats

GET /pay/api/getStats — optional start_at / end_at (ISO 8601; default pichhle 24 ghante). Deta hai: volume (window mein paid invoices ki USD value, current rates par estimate; bina price waale assets zero gine jaate hain), conversion (paid/created, percent), unique_users_count, created_invoice_count, paid_invoice_count aur actual window boundaries. volume aur conversion JSON numbers hain, strings nahi. Date parse na ho to 400 invalid_date milta hai.

Wo errors jo har method de sakta hai

HTTP	error.name	Kab
401	unauthorized	Token missing, invalid ya revoked
403	scope_required	Token mein method ka scope nahi
403	payouts_disabled	App ka payout mode off (sirf payout methods)
403	recipient_not_allowed	Recipient app ki list mein nahi (sirf payout methods)
400	invalid_request	Parameters parse nahi hote ya invalid hain (POST)
403	daily_cap_exceeded	App ki daily payout limit paar ho jaayegi
403	verification_required	Owner ke outgoing operations restricted hain; transfers, checks aur refunds par asar
503	merchant_payouts_paused	App-balance debits temporary paused hain
429	rate_limited	Rate limit paar
503	maintenance	Platform maintenance (write methods)
500	internal_error	Unexpected server error

Method-specific errors har method ke page par diye gaye hain.

JSON envelope ke bina errors

Plain text ya HTML error se akela pata nahi chalta ki error kis layer se aaya hai. HTTP status, response body aur response headers check karein.

Agar Cloudflare error code: 1010 return karta hai, to browser signature ke basis par client reject hua hai, request API tak pahunchne se pehle. Is Cloudflare error ki wajah token scopes nahi hain. Missing ya nonstandard User-Agent network protection trigger kar sakta hai. Apne client ka naam dene wala User-Agent header, jaise MyShop/1.0, bhejkar request retry karein; isse fix hone ki guarantee nahi hai. Error rahe to support ko HTTP status, response body aur response headers send karein. Pehle tokens aur cookies hata dein.