Mulai sebagai developer

Buat aplikasi di Mini App, salin token API-nya sekali, lalu mulai memanggil API. Semua pengaturannya ada di Lainnya → Merchant API.

Langkah

1. Buka Lainnya → Merchant API.
2. Isi Nama aplikasi (misalnya “Toko saya”) dan, kalau perlu, Webhook URL.
3. Tap Buat aplikasi.
4. Salin token API-nya sekarang juga. Token hanya ditampilkan sekali dan tidak akan muncul lagi — aplikasi cuma menyimpan hash-nya.
5. Kirim permintaan pertamamu dengan token itu di header TgCryptoPay-API-Token.

Panggilan pertama

Arahkan klienmu ke base URL API https://crypto.tgpaybot.com/pay/api, lalu panggil getMe untuk memastikan tokennya jalan. getBalance mengembalikan saldo aplikasimu, getCurrencies daftar aset yang bisa dipakai.

Metode baca memakai GET. Metode yang memindahkan dana — createInvoice, transfer, createCheck, dan pasangan delete-nya — sengaja dibuat hanya POST: jumlah dan kunci idempotensi tidak seharusnya tercatat di access log. Parameternya boleh dikirim sebagai body JSON, form-urlencoded, atau query param.

Mengelola aplikasi

Tiap kartu aplikasi di Merchant API menampilkan ID aplikasi dan saldonya, dan dari situ kamu bisa:

• Atur atau ganti webhook URL lalu simpan.
• Pilih event webhook tambahan — begitu webhook URL diisi, toggle Event webhook tambahan membuka jenis event lain di luar invoice_paid (lihat referensi webhook).
• Buat token terbatas — token API tambahan di bagian Token terbatas, masing-masing dibatasi pada hak akses yang kamu pilih (lihat referensi API).
• Ganti token — menerbitkan token baru dan langsung mematikan yang lama. Pakai ini kalau ada token yang bocor; token barunya juga cuma ditampilkan sekali, sama seperti saat dibuat.
• Hapus — aplikasinya tidak bisa lagi dipakai untuk autentikasi, tapi saldo dan riwayat pembayarannya tetap tersimpan. Menghapus aplikasi tidak pernah membuat dananya hilang.

Webhook

Kalau webhook URL diisi, aplikasi mengirim POST berisi body JSON bertanda tangan ke sana:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

Tanda tangannya ada di header TgCryptoPay-API-Signature (dengan Crypto-Pay-API-Signature sebagai alias kompatibilitas): HMAC-SHA256 atas body mentahnya, dengan kunci SHA-256 dari token API-mu. Periksa dulu sebelum mempercayai apa pun yang ada di payload.

Pengiriman diulang dengan exponential backoff selama jangka waktu yang panjang, dan update_id tetap sama di setiap percobaan — pakai nilai itu sebagai kunci deduplikasi, dan buat handler-mu idempoten.

invoice_paid selalu dikirim. Jenis event lain — faktur kedaluwarsa, cek yang diklaim, pengembalian dana, event langganan — harus kamu aktifkan sendiri lewat toggle Event webhook tambahan. Daftar lengkap, bentuk payload, dan jadwal pengulangannya ada di referensi webhook.

⚠️ Jaga token seperti kunci pribadi

Token itu memberi izin mengeluarkan dana dari saldo aplikasimu. Simpan di servermu, jangan pernah di aplikasi mobile, bundel front-end, atau file konfigurasi yang ikut ter-commit. Kalau ragu tokennya bocor atau tidak, ganti saja — penggantian berlaku seketika dan tidak dipungut biaya. Beri tiap server hanya yang memang dia butuhkan: token terbatas tanpa hak akses payouts bisa membuat faktur, tapi tidak akan pernah bisa memindahkan saldomu keluar.