Developer ke taur par shuruaat

Mini App mein ek app banayein, uska API token ek baar copy karein, aur API call karna shuru karein. Poora setup More → Merchant API ke neeche hai.

Steps

1. More → Merchant API kholein aur App banayein chunein.
2. App name daalein (jaise “My Store”) aur chahein to Webhook URL (optional).
3. Form ki terms accept karke App banayein tap karein. Maanga jaaye to PIN ya biometrics se confirm karein. App banaane se aap Merchant API terms accept karte hain — API ka use kis liye kar sakte hain aur kis liye nahi.
4. API token turant copy karein. Yeh sirf ek baar dikhta hai — app sirf iska hash store karta hai.
5. Token TgPayCrypto-API-Token header mein dekar pehli request bhejein.

Aapki pehli call

Apne client ko API base https://app.tgpaycrypto.com/pay/api par point karein aur getMe call karke pakka karein ki token kaam kar raha hai. getBalance aapke app ke balances deta hai, getCurrencies wo assets jo aap use kar sakte hain.

Read methods GET hain. Write methods, jaise createInvoice, transfer, createCheck, deleteInvoice aur deleteCheck, sirf POST hain. Parameters JSON body, form-urlencoded, ya query params ki tarah bhej sakte hain. Request body use karna behtar hai, taaki amounts aur idempotency keys URL access logs mein na aayein.

Testnet

Pehle test network par build karein — wahi API, wahi Mini App, test funds jinki koi value nahi:

	Mainnet	Testnet
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
API base	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
MCP server	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

Apps aur tokens alag hain: testnet token mainnet par nahi chalta, aur mainnet token testnet par nahi. Test funds ke liye testnet Mini App kholein aur home screen par Test coins lein tap karein. Faucet test pack ko normal deposits ki tarah credit karta hai; disabled networks ke assets skip hote hain. App dikhaata hai ki kya credit hua aur agli request kab kar sakte hain. Test invoices pay karne waale customer ke liye doosra Telegram account use kar sakte hain.

Deposits aur withdrawals simulated custody use karte hain, real blockchain transactions nahi. Testnet deposit address par kabhi real funds na bhejein. API contract shared hai, lekin available features, rates aur limits mainnet se alag ho sakte hain. Taiyaar hone par @tgpaycryptobot mein production app banaayein aur base URL badlein.

App manage karna

Merchant API mein app kholein. Uska app ID aur balance dikhta hai. Yahan se aap:

• Webhook URL set ya change karein — Webhook mein jaakar save karein.
• Extra webhook events chunein — Webhook section ke Extra webhook events toggles se invoice_paid ke alaawa event types chunein (webhooks reference dekhein).
• API ke payout recipients limit karein — Payout settings mein API ke through payouts naye app ke liye Koi bhi user hota hai; ise Sirf list wale users karein (recipients list karein), ya integration payouts nahi karti to Off karein — token leak hone par bachaav ke liye (payout mode dekhein).
• Restricted tokens banaayein — Access aur tokens kholkar Restricted tokens mein extra API tokens banaayein, har ek sirf chune scopes ke liye (API reference dekhein).
• Token rotate karein — Access aur tokens mein naya token issue hota hai aur purana turant invalid ho jaata hai. Token leak ho to yeh karein; naya token bhi creation ki tarah sirf ek baar dikhta hai.
• Delete — pehle available balance pay out karein; warna deletion app_has_balance se reject hoti hai. Delete karne se pehle outstanding checks aur pending payouts bhi resolve karein. App list se hat jaata hai aur tokens band ho jaate hain; payment history bani rahti hai.

Webhooks

Agar aap webhook URL set karte hain, to app uspar ek signed JSON body POST karta hai:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

Signature TgPayCrypto-API-Signature header mein hota hai (TgCryptoPay-API-Signature aur Crypto-Pay-API-Signature compatibility aliases hain): raw body ka HMAC-SHA256, jismein main API token ka SHA-256 key hota hai. Payload ki kisi bhi baat par bharosa karne se pehle verify karein.

Deliveries lambe waqt tak exponential backoff ke saath retry hoti hain, aur update_id har retry par wahi rehta hai — apni deduplication usi par karein aur apna handler idempotent rakhein.

Webhook URL configured ho to invoice_paid ke liye alag opt-in nahi chahiye. Doosre event types — expired invoices, claimed checks, refunds, subscription events — Extra webhook events toggles se opt in hote hain. Poori list, payload formats aur retry behavior webhooks reference mein hain.

⚠️ Token ko private key ki tarah sambhalein

Yeh aapke app balance se payouts authorize karta hai. Ise apne server par rakhein, kabhi kisi mobile app, front-end bundle ya commit ki gayi config mein nahi. Agar shak ho ki wo leak ho gaya hai, to rotate kar dein — rotation turant hota hai aur uska koi kharcha nahi. Aur har server ko sirf utna hi dein jitna use chahiye: sirf invoices scope wala restricted token invoices create aur delete kar sakta hai, lekin funds transfer, checks create ya refunds issue nahi kar sakta.