API reference: transfers aur checks

Payout ke methods. transfer aapke app balance se seedhe kisi Telegram user ke wallet mein funds bhejta hai; check ek aisa link hai jise claim kiya ja sakta hai aur jise aap pehle se fund karte hain. Conventions (auth, envelope, amounts, spend_id) Merchant API reference page par hain.

transfer

POST /pay/api/transfer — scope payouts, limit 30 per minute. Turant aur atomically settle hota hai; koi pending state nahi hoti.

Parameter	Type	Zaroori	Matlab
user_id	integer	haan	recipient ka Telegram user id. Recipient pehle se app ka user hona chahiye — kisi anjaan id par payout funds atkaane ke bajaay error deta hai
asset	string	haan	asset code
amount	string	haan	positive decimal string; saath hi platform ke per-transfer minimum aur maximum se bandha (maujooda rates par US-dollar-equivalent 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 = recipient ko Telegram par notify na karein

Result transfer object hota hai: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (hamesha completed), created_at, completed_at.

Errors: 404 user_not_found (recipient ne kabhi app use hi nahi kiya), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (per-transfer bounds se bahar), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, aur spend_id wali jodi 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

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

Ek parameter: items — ek array jismein har item poora transfer parameter set hota hai (user_id, asset, amount, spend_id, aur optional comment aur disable_send_notification). Batch ke andar spend_ids unique hone chahiye, warna kuch bhi chalne se pehle poori call 400 duplicate_spend_id ke saath fail ho jaati hai.

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), aur saath mein offset / count. {"items": [transfer, …]} deta hai, sabse naya pehle.

createCheck

POST /pay/api/createCheck — scope checks, limit 60 per minute. Aapke app balance se fund kiya gaya ek single-use check banata hai; jiske paas link ho wo koi bhi — ya sirf pinned user — use apne wallet mein claim kar sakta hai. Check bante hi amount lock ho jaati hai (getBalance mein wo available se onhold mein chala jaata hai).

Parameter	Type	Zaroori	Matlab
asset	string	haan	asset code
amount	string	haan	positive decimal string
pin_to_user_id	integer	nahi	sirf yahi Telegram user id claim kar sakta hai
pin_to_username	string	nahi	sirf yahi @username claim kar sakta hai (@ optional hai; jab pin_to_user_id bhi set ho to ise ignore kiya jaata hai). Username app ke kisi maujooda user ka hona chahiye
spend_id	string	nahi	idempotency key (extension) — ek use karein

Result check object hota 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. Claim hone par opt-in check_activated webhook fire hota hai.

Errors: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (pinned username kisi se match nahi karta), 409 insufficient_funds, aur spend_id wali jodi.

deleteCheck

POST /pay/api/deleteCheck — scope checks. Ek parameter: check_id. Jo check claim nahi hua use cancel karta hai aur locked amount aapke app balance mein wapas kar deta hai; true deta hai. Errors: 404 check_not_found, 409 check_not_active (pehle hi claim ya delete ho chuka).

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.