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.

API Crypto Bot-compatible hai: maujooda Crypto Bot integration sirf base URL aur token badalne ke baad kaam karta hai. Us contract se bahar ki har cheez neeche extension likhi hai.

Poore API ka machine-readable OpenAPI 3.1 spec — har method, object, error name aur webhook — in pages ke saath publish kiya jaata hai: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Ise code generators, API clients ya apne AI tools ko dein.

Base URL aur authentication

Sabhi methods https://crypto.tgpaybot.com/pay/api/<methodName> par hain.

Har request ko token ke saath authenticate karein, jo TgCryptoPay-API-Token header mein jaata hai (Crypto-Pay-API-Token compatibility alias ki tarah accept hota hai; dono bheje jaayein to canonical wala maana jaata hai). Jo token na ho, invalid ho, revoke ho chuka ho — ya kisi delete kiye gaye app ka ho — wo 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 par poora access, aur wahi akeli key jo webhooks sign karti hai.
• Restricted tokens (extension) — per app 10 tak live, jo More → Merchant API mein Restricted tokens ke neeche banaye jaate hain, har ek ke saath ek label aur scopes ka ek subset. Kisi ek ko revoke karna turant hota hai aur baaki par uska asar nahi padta; main token rotate karne se bhi in par asar nahi padta.

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

Scopes additive aur ek doosre se alag hain — invoices ka matlab read nahi hai, isliye jo server sirf invoices banata hai wo aisa token rakh sakta hai jo kuch bhi padh na sake. 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.

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.
• Har response JSON hai aur envelope hamesha ek hi: 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.
• Ek edge case: kisi GET method par type ke hisaab se galat query value (misaal ke liye offset=abc) HTTP 422 deti hai, jiski {"detail": …} body envelope ke bahar hoti hai. Query values sahi type ki bhejein.

Amounts

• Crypto amounts poore-coin units mein decimal strings hote hain ("10.5") — kabhi JSON numbers nahi. Responses ke saath amount_minor bhi aata hai (extension): integer minor-unit value ek string ki tarah, kyunki wei-scale integers JavaScript Number se overflow ho jaate hain.
• Per-asset decimals getCurrencies se aate hain — apna amount math hardcode karne ke bajaay wahin se chalayein.
• 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 ka banaya hua 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). 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.

Rate limits

Per app, uske sabhi tokens mein shared; limit paar karne par 429 rate_limited milta hai:

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

Read methods par rate limit nahi hai. Platform maintenance ke dauraan write methods 503 maintenance dete hain, jabki reads chalte rehte hain.

Catalog aur account methods

getMe

GET /pay/api/getMe — koi parameters nahi. App ki identity deta hai: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (wo extended webhook types jinke liye app ne opt-in kiya) aur upar bataye gaye token introspection fields scopes / token_name.

getBalance

GET /pay/api/getBalance — koi parameters nahi. Har supported asset ke liye ek row wala array deta hai, zero par bhi: currency_code, available (kharch kiya ja sakne wala balance), onhold (aapke abhi active checks mein locked funds) 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 parameters nahi. Crypto-se-fiat quotes: source, target, rate (ek fixed-point string) aur is_valid — false ka matlab hai ki poori table kisi purane cache se aa rahi hai; un rates ko sirf indicative maanein.

getStats

GET /pay/api/getStats — optional start_at / end_at (ISO 8601; default window pichhle 24 hours hai). volume (window mein paid invoices ki USD value), conversion (paid/created, percent), unique_users_count, created_invoice_count, paid_invoice_count aur effective window bounds deta hai. Jo date parse na ho wo 400 invalid_date deti hai.

Wo errors jo har method de sakta hai

HTTP	error.name	Kab
401	unauthorized	token na ho, invalid ho ya revoke ho chuka ho
403	scope_required	token ke paas us method ka scope na ho
400	invalid_request	parameters parse na hon ya invalid hon (POST)
429	rate_limited	rate limit paar ho gayi
503	maintenance	platform maintenance (write methods)
500	internal_error	unexpected server error

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