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 mein	Charge ka asset, jaise USDT. fiat ki jagah ise use karein
fiat	string	fiat mode mein	Price ki fiat currency (getCurrencies ki is_fiat rows)
accepted_assets	string / array	nahi	Sirf fiat mode: payer ke liye allowed assets — comma-separated string ("USDT,GRAM") ya JSON array. Na dein to 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 (zyaada se zyaada 2 decimal places)
open_amount	boolean	nahi	extension, sirf crypto mode: fixed amount nahi — payer payment ke waqt amount daalta hai (donations aur tips). amount ke saath use nahi kar sakte
description	string	nahi	1024 characters tak, payer ko dikhta hai
hidden_message	string	nahi	2048 characters tak, payer ko payment ke baad hi dikhta hai
payload	string	nahi	Aapka data, 4096 characters tak, invoice aur webhook mein waapas aata hai
allow_comments	boolean	nahi	Payer comment jod sakta hai (default true)
allow_anonymous	boolean	nahi	Payer apni pehchaan chhupa sakta hai (default true)
paid_btn_name	string	nahi	Payment ke baad button: viewItem, openChannel, openBot ya callback
paid_btn_url	string	nahi	Button ka http(s) URL — paid_btn_name set ho to zaroori
swap_to	string	nahi	Received payments ko is asset mein auto-swap karein. Swap ki koshish hoti hai: payment ke waqt swap na ho paaye to bhi payment bina swap ke successful hota hai
expires_in	integer	nahi	Invoice expiry tak seconds, 2678400 (31 din) tak; na dein ya 0 dein to default lifetime. Result mein expiration_date dekhein
rate_lock_seconds	integer	nahi	extension, sirf fiat mode: creation ke waqt conversion rates ko is window ke liye freeze karein (neeche dekhein)

Content review mein ho ya approve na hua ho to description, payment ke baad ka content aur button payers se chhupe reh sakte hain. Invoice ki amount phir bhi pay ki ja sakti hai.

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

• Identity aur status: invoice_id, hash (pay_url ke andar public id), status (active / paid / expired), pay_url — payer ko bhejne waala t.me link (bot_invoice_url, mini_app_invoice_url, web_app_invoice_url isi ke aliases hain).
• Amounts: amount (face value — fiat invoice par fiat units, warna crypto; unpaid open-amount invoice par null), amount_minor, aur paid fiat invoices par paid_asset / paid_amount / paid_fiat_rate — asal mein charge ki gayi crypto aur use hua rate.
• Fee: fee_asset / fee_amount, payment ke waqt record hote hain — accounts ke liye inhi ko maanein (fee aur usd_rate purane, deprecated Crypto Bot aliases hain). Fees aur limits dekhein.
• Payer: paid_by_user_id (payer anonymous ho to null), paid_anonymously, comment.
• Refunds (extension): refunded_amount / refunded_minor (kul refund) aur refunded_at, jo poora refund hone par set hota hai.
• Rate lock (extension): rate_lock_until aur rate_lock_rates — har asset ka recorded rate, lock na maanga ho to null.
• Creation ki details: description, hidden_message, payload, paid_btn_name / paid_btn_url, expiration_date (expires_at iska 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, 400 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 — kaafi funds aur payment confirmation hone par turant, bina network fee ke. Payer external wallet se bhi invoice ke liye funds laa sakta hai: option available ho to app deposit address aur payment deadline dikhaata hai. Deposit payer ke apne wallet mein credit hota hai. Automatic payment ke liye us address par deposit, kaafi available balance, outgoing-payment restriction na hona aur payment request aur invoice ka unexpired hona zaroori hai. Der se aaya deposit payer ke wallet mein rahta hai; yeh invoice pay hone ka saboot nahi hai. Dono tareekon mein aapko wahi milta hai: normal paid invoice aur webhook URL configured ho to invoice_paid event — koi extra parameter ya field handle nahi karni.

Fiat invoice par crypto amount payment ke waqt calculate hoti hai aur chune asset ki sabse chhoti unit tak round up hoti hai. Phir us crypto amount se merchant fee katti hai. Valid locked rate ya fresh rate na mile to stale rate par settle hone ke bajaay payer ka payment fail hota hai.

Fiat invoice par rate lock karna

Creation ke waqt har accepted asset ka current rate record karne ke liye rate_lock_seconds dein. Lock active ho to payer ko wahi recorded amounts dikhti hain aur payment usi rate par convert hota hai — is window mein rate badalne ka risk aapka hai. Server maangi duration ko supported range ke andar adjust karta hai. Asal deadline ke liye result ka rate_lock_until dekhein.

Lock expire hone ke baad unexpired invoice payment ke waqt ke rate par pay ho sakta hai. Dono deadlines ek saath rakhni hon to supported lock range ke andar expires_in use karein aur response ke expiration_date aur rate_lock_until milaayein.

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 se aage ka extension: asal paid crypto ka poora ya partial refund aapke app balance se payer ko deta hai. Anonymous payer ko bhi bina pehchaan dikhaaye refund hota hai. Fiat invoice par paid_asset aur paid_amount use karein; refund mein naya fiat conversion nahi hota.

Parameter	Type	Zaroori	Matlab
invoice_id	integer	haan	Paid invoice
amount	string	nahi	Original payment asset mein refund ki crypto amount (fiat invoices ke liye paid_asset). Na dein to poori unrefunded amount. Partial refunds ka total original paid crypto amount tak ho sakta hai
spend_id	string	nahi	Idempotency key — dein, taaki timeout ke baad retry par dobara refund ke bajaay wahi result mile

Result updated invoice object hai, jismein kul refunded_amount / refunded_minor hota hai; poora refund hone par refunded_at set hota hai. Status paid hi rahta hai. Platform fee waapas nahi hoti. App mein original payment asset ka kaafi balance chahiye, bhale hi swap_to ne received amount ko doosre asset mein convert kiya ho. Har refund par opt-in refund_completed webhook aata 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.