API reference: invoices aur refunds

Invoice ke methods: createInvoice, getInvoices, deleteInvoice, refundInvoice. Conventions (auth, envelope, amounts, spend_id) Merchant API reference page par hain; step-by-step walkthrough hai Invoices se payments accept karna.

createInvoice

POST /pay/api/createInvoice — scope invoices, limit 60 per minute.

Parameter	Type	Zaroori	Matlab
currency_type	string	nahi	crypto (default) ya fiat
asset	string	crypto mode	jis asset mein charge karna hai, misaal ke liye USDT. fiat ke saath allowed nahi
fiat	string	fiat mode	wo fiat currency jismein price rakhi hai (getCurrencies ki is_fiat rows)
accepted_assets	string / array	nahi	sirf fiat mode: wo assets jinse payer pay kar sakta hai — comma se alag ki gayi string ("USDT,GRAM") ya ek JSON array. Na dein = sabhi supported assets
amount	string	haan, jab tak open_amount set na ho	positive decimal string: crypto mode mein asset units, fiat mode mein fiat units (max 2 decimal places)
open_amount	boolean	nahi	extension, sirf crypto mode: koi fixed amount nahi — payer pay karte waqt khud daalta hai (donations aur tips). amount ke saath mutually exclusive
description	string	nahi	1024 characters tak, payer ko dikhta hai
hidden_message	string	nahi	2048 characters tak, payer ko sirf payment ke baad dikhaya jaata hai
payload	string	nahi	aapke apne data ke 4096 characters tak, jo invoice aur webhook par wapas milte hain
allow_comments	boolean	nahi	payer ko comment jodne dein (default true)
allow_anonymous	boolean	nahi	payer ko apni pehchaan chhupane dein (default true)
paid_btn_name	string	nahi	payment ke baad wala button: viewItem, openChannel, openBot, ya callback
paid_btn_url	string	nahi	us button ka http(s) URL — jab paid_btn_name set ho to zaroori
swap_to	string	nahi	aaye hue payments ko apne aap is asset mein swap karein. Best-effort: agar pay ke waqt swap na chal sake, to payment phir bhi bina swap ke succeed hota hai
expires_in	integer	nahi	invoice expire hone tak ke seconds, 2678400 (31 din) tak; na dein ya 0 = kabhi nahi
rate_lock_seconds	integer	nahi	extension, sirf fiat mode: banate waqt conversion rates ko is window ke liye freeze karein (neeche dekhein)

Result — aur invoice_paid webhook ka payload — invoice object hota hai. Uske main fields:

• Identity aur state: invoice_id, hash (pay_url ke andar ka public id), status (active / paid / expired), pay_url — wo t.me link jo aap payer ko bhejte hain (bot_invoice_url, mini_app_invoice_url, web_app_invoice_url uske aliases hain).
• Amounts: amount (face value — fiat invoice par fiat units, warna crypto; open-amount invoice ke pay hone tak null), amount_minor, aur paid fiat invoices par paid_asset / paid_amount / paid_fiat_rate — asal mein charge hua crypto aur use kiya gaya rate.
• Fee: fee_asset / fee_amount, payment ke waqt stamp hote hain — aapki books ke liye authoritative figure (fee aur usd_rate deprecated Crypto Bot aliases hain). Dekhein fees aur limits.
• Payer: paid_by_user_id (null jab payer ne anonymity chuni ho), paid_anonymously, comment.
• Refunds (extension): refunded_amount / refunded_minor (cumulative) aur refunded_at, jo poora refund ho jaane par stamp hota hai.
• Rate lock (extension): rate_lock_until aur rate_lock_rates — stamp kiye gaye per-asset rates, null jab koi lock na maanga gaya ho.
• Jaisa banaya gaya tha: description, hidden_message, payload, paid_btn_name / paid_btn_url, expiration_date (expires_at uska alias hai), swap fields (swap_to, is_swapped, swapped_to, swapped_rate, swapped_output, …).

Errors: 400 invalid_currency (asset/fiat aapas mein gadbad), 400 invalid_amount, 404 unknown_asset, 400 unsupported_fiat, 400 paid_btn_url_required, aur rate-lock requests ke liye 400 rate_lock_fiat_only, 409 ratelock_disabled, 409 rate_unavailable (kisi accepted asset ka fresh rate nahi — dobara koshish karein).

Invoices pay kaise hote hain

Payer Mini App mein apne wallet balance se pay karta hai — turant, bina kisi network fee ke. Payer invoice ko kisi external wallet se bhi fund kar sakta hai: app use ek deposit address dikhata hai, uska transfer uske apne wallet mein aata hai, aur aate hi invoice apne aap settle ho jaata hai. Dono soorat mein aapko ek hi cheez dikhti hai: ek normal paid invoice aur ek invoice_paid webhook — handle karne ke liye koi extra parameters ya fields nahi hain.

Fiat invoice par crypto amount payment ke waqt nikaala jaata hai aur aapke fayde mein upar round hota hai, isliye aapko fiat face value se kam kabhi nahi milta. Agar koi fresh rate na ho, to payment purane rate par settle hone ke bajaay payer ke liye fail ho jaata hai.

Fiat invoice par rate lock karna

rate_lock_seconds bhejein taaki banate waqt har accepted asset ka maujooda rate stamp ho jaaye. Jab tak lock live hai, payer ko bilkul wahi stamp kiye gaye amounts dikhte hain, aur payment usi stamp kiye gaye rate par convert hota hai — us window ka rate risk aap uthate hain. Server window ko 60 seconds aur platform maximum (abhi 15 minutes) ke beech clamp karta hai.

Lock khatam hone par invoice pay hone layak bana rehta hai aur chupchaap pay-time conversion par laut aata hai. Agar aap chahte hain ki invoice quote ke saath hi khatam ho jaaye, to expires_in ko usi value par set karein.

getInvoices

GET /pay/api/getInvoices — scope read. Filters: asset, fiat, invoice_ids (comma se alag), status (active / paid / expired — expired ek extension hai; active un invoices ko chhod deta hai jinki deadline nikal chuki hai), aur saath mein offset / count. {"items": [invoice, …]} deta hai, sabse naya pehle.

deleteInvoice

POST /pay/api/deleteInvoice — scope invoices. Ek parameter: invoice_id. Kisi unpaid invoice ko cancel karta hai aur true deta hai. Errors: 404 invoice_not_found, 409 invoice_already_paid — paid invoice delete nahi ho sakta, paisa pehle hi move ho chuka hai.

refundInvoice

POST /pay/api/refundInvoice — scope refunds, limit 30 per minute. Crypto Bot ke upar ek extension: kisi paid invoice ka face amount — ya uska ek hissa — aapke app balance se usi ko wapas karta hai jisne pay kiya tha, anonymous payers bhi shaamil, unki pehchaan bataye bina.

Parameter	Type	Zaroori	Matlab
invoice_id	integer	haan	wo paid invoice
amount	string	nahi	kitna refund karna hai, invoice ke asset mein. Na dein = jitna refund hona baaki hai wo poora. Partial refunds jud kar face amount tak pahunch sakte hain
spend_id	string	nahi	idempotency key — ek use karein, taaki timeout wali retry do baar refund karne ke bajaay replay kare

Result cumulative refunded_amount / refunded_minor ke saath updated invoice object hota hai; invoice poora refund ho jaane par refunded_at stamp hota hai. Status paid hi rehta hai. Platform fee wapas nahi hoti. Har refund opt-in refund_completed webhook fire karta hai.

Errors: 404 invoice_not_found, 409 invoice_not_paid, 409 already_refunded (refund karne ko kuch bacha nahi), 409 amount_too_big (jitna refund hona baaki hai usse zyada), 409 insufficient_funds, 400 invalid_amount, aur spend_id wali jodi 409 idempotency_conflict / 409 idempotency_in_progress.