Referensi API: transfer dan cek kripto

Metode untuk mengirim dana keluar. Transfer mengirim dana dari saldo aplikasimu langsung ke dompet pengguna Telegram; cek kripto adalah link yang bisa diklaim dan kamu danai di muka. Konvensi umum (autentikasi, envelope, jumlah, spend_id) ada di halaman Referensi Merchant API.

transfer

POST /pay/api/transfer — scope payouts, batas 30 per menit. Selesai seketika dan atomik; tidak ada status menunggu.

Parameter	Tipe	Wajib	Keterangan
user_id	integer	ya	id pengguna Telegram penerima. Penerimanya harus sudah jadi pengguna aplikasi — pembayaran ke id yang tidak dikenal akan error, bukan membuat dananya menggantung
asset	string	ya	kode aset
amount	string	ya	string desimal positif; juga dibatasi minimum dan maksimum per transfer dari platform (perkiraan setara dolar AS pada kurs saat ini)
spend_id	string	ya	kunci idempotensi, 1–64 karakter, unik per pembayaran
comment	string	tidak	maksimal 1024 karakter, ditampilkan ke penerima
disable_send_notification	boolean	tidak	true = jangan beri tahu penerima di Telegram

Hasilnya adalah objek transfer: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (selalu completed), created_at, completed_at.

Error: 404 user_not_found (penerimanya belum pernah memakai aplikasi), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (di luar batas per transfer), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, dan pasangan spend_id 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — scope payouts, batas 10 per menit. Ekstensi untuk pembayaran massal: sampai 100 transfer dalam satu panggilan.

Satu parameter: items — array yang tiap itemnya berisi satu set parameter transfer lengkap (user_id, asset, amount, spend_id, plus comment dan disable_send_notification yang opsional). Semua spend_id harus unik di dalam batch itu; kalau tidak, seluruh panggilan gagal dengan 400 duplicate_spend_id sebelum ada yang dieksekusi.

Tiap item diselesaikan sendiri-sendiri, sesuai urutan — satu item yang gagal tidak pernah membatalkan item lainnya. Panggilannya tetap mengembalikan HTTP 200 dengan ok: true meski ada item yang gagal, jadi selalu periksa tiap item satu per satu:

• berhasil: {"ok": true, "spend_id": "…", "result": <transfer object>}
• gagal: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} dengan nama error yang sama seperti transfer tunggal.

Item batch berbagi ruang idempotensi dengan transfer tunggal: mengulang seluruh batch — atau mengirim ulang satu itemnya sebagai transfer tunggal dengan spend_id yang sama — akan mengulang hasil lama, bukan membayar dua kali.

getTransfers

GET /pay/api/getTransfers — scope read. Filter: asset, transfer_ids (dipisah koma), spend_id (cocok persis — cari satu pembayaran pakai kuncimu sendiri), plus offset / count. Mengembalikan {"items": [transfer, …]}, diurutkan dari yang terbaru.

createCheck

POST /pay/api/createCheck — scope checks, batas 60 per menit. Membuat cek sekali pakai yang didanai dari saldo aplikasimu; siapa pun yang punya linknya — atau hanya pengguna tertentu, kalau ceknya dikunci ke dia — bisa mengklaimnya ke dompetnya. Jumlahnya terkunci begitu ceknya dibuat (dananya berpindah dari available ke onhold di getBalance).

Parameter	Tipe	Wajib	Keterangan
asset	string	ya	kode aset
amount	string	ya	string desimal positif
pin_to_user_id	integer	tidak	hanya id pengguna Telegram ini yang boleh mengklaim
pin_to_username	string	tidak	hanya @username ini yang boleh mengklaim (tanda @ boleh tidak ditulis; diabaikan kalau pin_to_user_id juga diisi). Username-nya harus milik pengguna aplikasi yang sudah ada
spend_id	string	tidak	kunci idempotensi (ekstensi) — pakai saja

Hasilnya adalah objek cek: check_id, hash, asset, amount, amount_minor, bot_check_url (link klaim t.me), status (active / activated), pin_to_user_id, created_at, activated_at. Klaim memicu webhook check_activated yang perlu kamu aktifkan dulu.

Error: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (username yang dikunci tidak cocok dengan siapa pun), 409 insufficient_funds, dan pasangan spend_id.

deleteCheck

POST /pay/api/deleteCheck — scope checks. Satu parameter: check_id. Membatalkan cek yang belum diklaim dan mengembalikan jumlah terkuncinya ke saldo aplikasimu; mengembalikan true. Error: 404 check_not_found, 409 check_not_active (sudah diklaim atau dihapus).

getChecks

GET /pay/api/getChecks — scope read. Filter: asset, check_ids (dipisah koma), status (active / activated), plus offset / count. Mengembalikan {"items": [check, …]}, diurutkan dari yang terbaru; cek yang sudah dihapus tidak pernah ikut dikembalikan.