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). Crypto mode mein ignore hota hai — fiat mein price set karne ke liye currency_type: "fiat" dein
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, max 512 characters — paid_btn_name set ho to zaroori, uske bina ignore hota hai
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, jo abhi bhi 31 din hai. 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 (hamesha crypto minor units: crypto invoice par face value; fiat invoice par payment tak null, uske baad paid_asset ki minor units; open-amount invoice par payment tak null), aur paid fiat invoices par paid_asset / paid_amount / paid_fiat_rate — asal mein charge ki gayi crypto aur use hua rate. Fiat invoice par asset payment ke baad bhi null rehta hai.
• 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.
• Timestamps aur payment data: created_at, paid_at, paid_usd_rate (payment ke waqt record hua USD rate).
• Creation ki details: currency_type, accepted_assets, open_amount, is_anonymous, 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 (crypto mode mein asset missing; fiat mode mein fiat missing, saath mein asset bhi bheja, ya open_amount set kiya), 400 invalid_amount (asset ki precision par zero ho jaane wala amount bhi), 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). 400 invalid_request galat parameters ke liye hai: unknown currency_type ya paid_btn_name, length limit se lamba text, 0–2678400 ke baahar expires_in, JSON number ki tarah bheja gaya amount.

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. Parameter 0 se 86400 seconds tak leta hai: 0 ka matlab rate lock nahi chahiye. Baaki values supported window mein adjust hoti hain — kam se kam 60 seconds aur zyada se zyada platform maximum. 0–86400 ke baahar ki value par 400 invalid_request milta 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 (default 100, max 1000). {"items": [invoice, …]} deta hai, sabse naya pehle.

deleteInvoice

POST /pay/api/deleteInvoice — scope invoices. Ek parameter: invoice_id. Kisi unpaid invoice ko — active ho ya expired — delete karta hai aur true deta hai. Invoice sirf mark nahi hota, poori tarah hat jaata hai: getInvoices se gayab ho jaata hai, uska pay_url kaam karna band kar deta hai, aur koi webhook nahi aata. Deletion ka record chahiye to apne system mein rakhein. Errors: 404 invoice_not_found, 409 invoice_already_paid — paid invoice delete nahi ho sakta, kyunki 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, 400 invalid_request (invoice_id missing ya spend_id 64 characters se lamba), 403 verification_required (owner ke outgoing operations restricted hain), 503 merchant_payouts_paused, aur spend_id wali jodi 409 idempotency_conflict / 409 idempotency_in_progress.