Invoices se payments accept karna

Invoice se aap Telegram user se payment lete hain. API se invoice banaayein, payer ko uska link bhejein aur successful payment par merchant fee katne ke baad amount aapke app balance mein aa jaati hai.

Flow

1. createInvoice se invoice banaayein, asset aur amount dekar (ya fiat price — neeche dekhein).
2. Response ka link payer ko bhejein. Use kholne par app ki Invoice pay karein screen aati hai.
3. Payer confirm karta hai aur balance se pay karta hai — turant, bina network fee ke. Balance kam ho to external wallet se funds laa sakta hai, jab yeh option available ho. Automatic payment ke liye deadline se pehle kaafi credited balance aur outgoing-payment restriction na hona zaroori hai. Sirf deposit ho jaana invoice payment ka saboot nahi hai.
4. Aapko notification milta hai. Webhook URL configured ho to payment ke baad invoice_paid event queue mein judta hai. Fee katne ke baad amount aapke app mein aati hai.
5. Order poora karein. Pehle webhook signature verify karein, invoice ko apne order se milaayein aur paid status confirm karein. getInvoices se bhi status check kar sakte hain; ab aur blockchain confirmations nahi chahiye.

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.

swap_to set karke incoming payments ko ek asset mein convert kar sakte hain, jab conversion available ho. Conversion na ho paaye to bhi payment original asset mein successful hota hai; is_swapped aur swapped_* fields check karein.

Kaam ke invoice options

• description — payer ko Invoice pay karein screen par dikhta hai.
• hidden_message — payer ko payment ke baad hi milta hai. Alag delivery channel ke bina code, key ya link dene ka tareeka.
• payload — aapki apni string, jo webhook mein waapas aati hai. Yahan order ID rakhein.
• expires_in — time limit, jiske baad invoice pay nahi ho sakta.
• paid_btn_name / paid_btn_url — payment ke baad payer ko dikhne waala button, jo aapke bot, channel ya item page par le jaata hai.
• open_amount — fixed amount nahi; payer payment ke waqt amount daalta hai. Donations aur tips ke liye upyogi.

Description, hidden content aur payment ke baad waala button content approve hone tak payers se chhupe reh sakte hain. Invoice banaate hi inke dikhne par nirbhar na rahein.

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

Refunds

refundInvoice asal mein pay ki gayi crypto — ya uska koi hissa — app balance se usi payer ko waapas karta hai, anonymous payers ko bhi, bina unki pehchaan dikhaaye. Partial refunds ka total original paid crypto amount tak ho sakta hai; invoice ise refunded_amount mein track karta hai. Fiat invoices ke refunds mein paid_asset aur paid_amount use hote hain, fiat face value nahi. Automatic swap ke baad bhi app mein original payment asset ka kaafi balance hona chahiye. spend_id dein taaki timeout ke baad retry par dobara refund ke bajaay wahi result mile. Platform fee waapas nahi hoti.

⚠️ Order poora karne se pehle webhook signature verify karein

Koi bhi aapke webhook URL par POST kar sakta hai. Payment ko asli maanne se pehle TgPayCrypto-API-Signature header check karein — raw request body ka HMAC-SHA256, jismein main API token ka SHA-256 key hota hai. update_id se duplicates rokein taaki retry par order dobara na bheja jaaye.