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, lalu pilih Buat aplikasi.
2. Isi Nama aplikasi (misalnya “Toko saya”) dan, kalau perlu, Webhook URL (opsional).
3. Setujui ketentuan pada formulir, lalu tap Buat aplikasi. Konfirmasi dengan PIN atau biometrik jika diminta. Membuat aplikasi berarti menerima ketentuan Merchant API — untuk apa API boleh dan tidak boleh dipakai.
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 TgPayCrypto-API-Token.

Panggilan pertama

Arahkan klienmu ke base URL API https://app.tgpaycrypto.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 tulis seperti createInvoice, transfer, createCheck, deleteInvoice, dan deleteCheck memakai hanya POST. Parameternya boleh dikirim sebagai body JSON, form-urlencoded, atau query param. Sebaiknya gunakan body agar jumlah dan kunci idempotensi tidak tercatat di log akses URL.

Testnet

Bangun integrasimu di testnet dulu — API yang sama, Mini App yang sama, dana uji cobanya tidak bernilai:

	Mainnet	Testnet
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
Base URL API	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
Server MCP	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

Aplikasi dan tokennya terpisah: token testnet tidak jalan di mainnet, dan sebaliknya. Untuk mendapatkan dana, buka Mini App testnet lalu tap Dapatkan koin uji coba di layar utama. Faucet menambahkan paket dana uji sebagai deposit biasa; aset pada jaringan yang dinonaktifkan dilewati. Aplikasi menampilkan dana yang masuk dan kapan kamu boleh meminta lagi. Kamu bisa memakai akun Telegram kedua sebagai pelanggan yang membayar faktur uji.

Deposit dan penarikan menggunakan simulasi kustodian tanpa transaksi blockchain sungguhan. Jangan pernah mengirim dana sungguhan ke alamat deposit testnet. Kontrak API sama, tetapi fitur yang tersedia, kurs, dan batas bisa berbeda dari mainnet. Setelah selesai, buat aplikasi produksi di @tgpaycryptobot dan ganti base URL.

Mengelola aplikasi

Buka aplikasi di Merchant API untuk melihat ID aplikasi dan saldonya. Dari situ kamu bisa:

• Atur atau ganti webhook URL di bagian Webhook, lalu simpan.
• Pilih event webhook tambahan — pilihan Event webhook tambahan di bagian Webhook menentukan jenis event lain di luar invoice_paid (lihat referensi webhook).
• Persempit siapa yang boleh dibayar lewat API — di Pengaturan pembayaran, Pembayaran lewat API untuk aplikasi baru disetel ke Semua pengguna; ubah ke Hanya pengguna dalam daftar (lalu daftarkan penerimanya) atau Nonaktif kalau integrasimu tidak pernah membayar siapa pun — pengaman kalau tokennya bocor (lihat mode pembayaran).
• Buat token terbatas — buka Akses dan token untuk membuat token API tambahan di bagian Token terbatas, masing-masing dibatasi pada hak akses yang kamu pilih (lihat referensi API).
• Ganti token — buka Akses dan token untuk menerbitkan token baru dan langsung menonaktifkan yang lama. Pakai ini kalau ada token yang bocor; token barunya juga cuma ditampilkan sekali, sama seperti saat dibuat.
• Hapus — keluarkan saldo yang tersedia terlebih dahulu; jika belum, penghapusan ditolak dengan app_has_balance. Selesaikan juga cek yang masih beredar dan pembayaran yang menunggu. Aplikasi hilang dari daftar dan tokennya berhenti bekerja; riwayat pembayaran tetap disimpan.

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 TgPayCrypto-API-Signature (dengan TgCryptoPay-API-Signature dan Crypto-Pay-API-Signature sebagai alias kompatibilitas): HMAC-SHA256 atas body mentahnya, dengan kunci SHA-256 dari token API utamamu. 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 tidak perlu diaktifkan terpisah jika URL webhook sudah diatur. 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 dengan hak akses invoices saja bisa membuat dan menghapus faktur, tetapi tidak bisa mentransfer dana, membuat cek, atau mengembalikan dana.