API reference: transfers aur checks

Yeh payout ke methods hain. transfer aapke app balance se kisi Telegram user ke wallet mein funds send karta hai, ya naye recipient ke bot kholne tak funds hold par rakhta hai. check ek claim link hai, jiske liye amount aapke balance se pehle hi lock ho jaati hai. Conventions (auth, envelope, amounts, spend_id) Merchant API reference page par hain.

Paisa bahar bhejne wale teeno methods app ke payout mode ko maante hain: naya app shuru se hi kisi ko bhi pay kar sakta hai; agar owner ne recipients par restriction laga di ho, to sirf list wale recipients ko pay kiya ja sakta hai (403 recipient_not_allowed) ya kisi ko bhi nahi (403 payouts_disabled). Mode owner Mini App mein set karta hai; API se yeh nahi badalta. Payouts kis liye ho sakte hain, yeh Merchant API ki terms tay karti hain.

transfer

POST /pay/api/transfer — scope payouts, limit 30 per minute. Known recipient ko payout turant milta hai. Unknown username par pending transfer banta hai: us username waala user bot khole tab tak funds escrow mein rahte hain. Unclaimed funds 30 din ki expiry (expires_at) ke baad app balance mein waapas aate hain. Apne accounts mein funds ginna shuru karne se pehle status: "returned" se return confirm karein. invite_url khud forward karein — bot us vyakti ko message nahi kar sakta jisne kabhi use start nahi kiya. Final status completed ya returned hai; transfer_completed aur transfer_returned webhooks subscribe karein ya getTransfers poll karein.

Parameter	Type	Zaroori	Matlab
user_id	integer	user_id / username mein se theek ek	Recipient ka Telegram ID; app ka maujooda user hona chahiye
username	string	user_id / username mein se theek ek	Recipient username, @ ke saath ya bina; unknown username par pending payout banta hai
asset	string	haan	Asset code
amount	string	haan	Positive decimal string; platform ki per-transfer minimum aur maximum bhi laagu hain (current rates par US-dollar estimate)
spend_id	string	haan	Idempotency key, 1–64 characters, har payout ke liye unique
comment	string	nahi	1024 characters tak, recipient ko dikhta hai
disable_send_notification	boolean	nahi	true se immediate payout ka recipient notification rukta hai; pending transfer claim karne par phir bhi notification jaata hai

Result transfer object hota hai: transfer_id, hash, user_id, recipient_username, asset, amount, amount_minor, spend_id, comment, status (pending / completed / returned), created_at, completed_at, expires_at, invite_url. Naye recipient ke aane tak user_id null ho sakta hai; transfer complete hone tak completed_at null rehta hai.

Errors: 403 payouts_disabled / 403 recipient_not_allowed (payout mode), 404 user_not_found (ID unknown hai ya recipient available nahi), 400 invalid_recipient (invalid recipient username), 400 amount_too_small / 400 amount_too_big (per-transfer bounds ke baahar), 409 insufficient_funds, 400 unknown_asset, 400 invalid_amount, aur spend_id pair 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — scope payouts, limit 10 per minute. Mass payouts ke liye extension: ek call mein 100 transfers tak.

Ek parameter: items — array, jiske har item mein poora transfer parameter set hota hai (user_id ya username, asset, amount, spend_id, optional comment aur disable_send_notification). Batch mein spend_id unique hone chahiye; warna kuch bhi execute hone se pehle poori call 400 duplicate_spend_id se fail hoti hai. Invalid item structure, app ka payout mode ya daily limit bhi kisi payout se pehle poori request reject kar sakte hain. Accept hone ke baad results result.items mein milte hain.

Items alag-alag, order mein settle hote hain — ek item fail hone se baaki items roll back nahi hote. Kuch items fail hone par bhi call HTTP 200 aur ok: true deti hai, isliye har item hamesha check karein:

• success: {"ok": true, "spend_id": "…", "result": <transfer object>}
• failure: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} — error names wahi jo ek single transfer mein hote hain.

Batch items single transfers ke saath wahi idempotency namespace share karte hain: poora batch dobara bhejna — ya kisi ek item ko usi spend_id ke saath single transfer ki tarah dobara bhejna — do baar pay karne ke bajaay replay karta hai.

getTransfers

GET /pay/api/getTransfers — scope read. Filters: asset, transfer_ids (comma se alag), spend_id (exact match — apni hi key se koi payout dhoondhein), status (pending / completed / returned), aur saath mein offset / count. {"items": [transfer, …]} deta hai, sabse naya pehle.

createCheck

POST /pay/api/createCheck — scope checks, limit 60 per minute. Default se app balance ka single-use check banta hai. Link waala koi bhi vyakti, ya sirf pinned user, ise claim kar sakta hai. recipients extension har recipient ki alag amount ke saath named list banaata hai. Creation par total lock hota hai (getBalance mein available se onhold mein jaata hai). Check creation par transfers waali amount aur daily payout limits laagu hain.

Parameter	Type	Zaroori	Matlab
asset	string	haan	Asset code
amount	string	jab tak recipients set na ho	Positive decimal string; recipients ho to list se total calculate hota hai
pin_to_user_id	integer	nahi	Sirf yeh Telegram ID claim kar sakti hai
pin_to_username	string	nahi	Sirf yeh @username claim kar sakta hai (@ optional; pin_to_user_id bhi set ho to username ignore hota hai). Username app ke maujooda user ka hona chahiye
spend_id	string	nahi	Idempotency key (extension) — use karein
recipients	array	nahi	Extension: 1–100 items, har ek mein user_id ya username aur positive decimal-string amount. Pinned user ke saath use nahi kar sakte
password	string	nahi	Extension: claim karne ka password; 64 characters tak
expires_in	integer	nahi	Extension: seconds mein lifetime; na dein ya 0 dein to expiry nahi

Result check object hai: check_id, hash, asset, amount, amount_minor, bot_check_url (t.me claim link), status (active / activated), pin_to_user_id, created_at, activated_at, expires_at aur recipients (normal check mein null; warna har entry mein user_id, username, amount, amount_minor, claimed_at). Har claim par opt-in check_activated webhook aata hai; named-list claim mein activated_slot bhi hota hai. Expiry par unclaimed amount waapas hoti hai; named-list expiry par check_expired aa sakta hai.

Current response har aise check ko status: "active" dikhaata hai jo poora claim nahi hua — expired check ko bhi. expires_at bhi check karein; sirf active ko link abhi claim hone laayak hone ka saboot na maanein.

Errors: 403 payouts_disabled / 403 recipient_not_allowed (payout mode — allowlist mode mein har pinned ya named recipient list mein hona chahiye), 400 unknown_asset, 400 invalid_amount, 404 user_not_found (pinned username kisi ka nahi mila), 409 insufficient_funds aur spend_id pair.

deleteCheck

POST /pay/api/deleteCheck — scope checks. Ek parameter: check_id. Active check cancel karta hai aur unclaimed amount app balance mein waapas karta hai; result true hai. Errors: 404 check_not_found, 409 check_not_active (poora claim hua, expired ya deleted).

getChecks

GET /pay/api/getChecks — scope read. Filters: asset, check_ids (comma se alag), status (active / activated), aur saath mein offset / count. {"items": [check, …]} deta hai, sabse naya pehle; delete kiye gaye checks kabhi list mein nahi aate.