Invoices se payments accept karna

Invoice hi wo tareeka hai jisse aap kisi Telegram user ko charge karte hain. Aap API se ek invoice banate hain, payer ko uska link bhejte hain, aur uske confirm karte hi aapka app balance credit ho jaata hai.

Flow

1. Invoice banayein — createInvoice se, asset aur amount dete hue (ya ek fiat price — neeche dekhein).
2. Payer ko link bhejein — wahi jo response mein aata hai. Use kholte hi wo app ki Pay screen par pahunch jaata hai.
3. Wo confirm karte hain aur apne balance se pay karte hain — turant, bina kisi network fee ke. Jis payer ke paas poora balance nahi hai wo invoice ko kisi external wallet se fund kar sakta hai; uska transfer aate hi invoice apne aap settle ho jaata hai, aur aapke liye yeh bilkul waisa hi dikhta hai.
4. Aapko notify kiya jaata hai. invoice_paid webhook fire hota hai, aur amount aapke app balance mein aa jaata hai.
5. Order poora karein. Aur kisi cheez ka intezaar na karein; us waqt payment final ho chuka hota hai.

Agar aap webhook ke bajaay poll karna chahte hain, to getInvoices aapke invoices unke maujooda status ke saath deta hai. Webhook tez raasta hai — polling fallback hai.

Fiat mein pricing

Invoice ki price crypto mein ho sakti hai, ya kisi fiat currency mein accepted assets ki list ke saath. Phir payer un accepted assets mein se jo bhi uske paas ho usmein settle karta hai, payment ke waqt ke rate par convert hokar. Jis shop ka catalog kisi fiat currency mein hota hai, uske liye aam taur par yahi option chuna jaata hai.

Agar aap pakki price quote karna chahte hain, to rate_lock_seconds conversion rates ko banate waqt ek limited window ke liye freeze kar deta hai — payer ko bilkul wahi locked amounts dikhte hain, aur un minutes ka rate risk aap uthate hain. Detail invoices reference mein hai.

Aap swap_to bhi set kar sakte hain, taaki aane wale payments aate hi ek hi asset mein convert ho jaayein — apna balance kisi stablecoin mein rakhne ke liye kaam ka, aur swaps khud chalane ki zaroorat nahi.

Kaam ke invoice options

• description — payer ko Pay screen par dikhta hai.
• hidden_message — payer ko sirf pay karne ke baad dikhaya jaata hai. Kisi code, key ya link ko bina alag delivery channel ke dene ka yahi tareeka hai.
• payload — aapki apni opaque string, jo webhook par wapas mil jaati hai. Apna order ID yahan rakhein.
• expires_in — ek time limit, jiske baad invoice pay nahi kiya ja sakta.
• paid_btn_name / paid_btn_url — pay karne ke baad payer ko dikhne wala button, jo use aapke bot, channel ya item page par wapas le jaata hai.
• open_amount — koi fixed amount nahi; payer pay karte waqt khud daalta hai. Donations aur tips ke liye bilkul sahi.

Jo invoice pay nahi hua use deleteInvoice se cancel kiya ja sakta hai.

Refunds

refundInvoice kisi paid invoice ka face amount — ya uska koi bhi hissa — aapke app balance se usi ko wapas karta hai jisne pay kiya tha, anonymous payers bhi shaamil, aur unki pehchaan bataye bina. Partial refunds jud kar face amount tak pahunch sakte hain; invoice unhe refunded_amount mein track karta hai. Ek spend_id bhejein taaki timeout hone par retry dobara refund karne ke bajaay purana result replay kare. Platform fee refund nahi hoti.

⚠️ Order poora karne se pehle webhook signature verify karein

Aapke webhook URL par koi bhi POST kar sakta hai. Kisi payment ko asli maanne se pehle TgPayCrypto-API-Signature header check karein — raw request body par HMAC-SHA256, jiski key aapke API token ka SHA-256 hai — aur update_id par dedupe karein taaki retry se order do baar ship na ho jaaye.