Referensi Merchant API

Konvensi yang dipakai semua metode, plus metode katalog yang hanya membaca. Halaman per metode: faktur dan pengembalian dana, transfer dan cek kripto, langganan, webhook.

API-nya kompatibel dengan Crypto Bot: integrasi Crypto Bot yang sudah ada tinggal ganti base URL dan tokennya. Semua yang di luar kontrak itu ditandai ekstensi di bawah.

Spesifikasi OpenAPI 3.1 yang bisa dibaca mesin untuk seluruh API — tiap metode, objek, nama error, dan webhook — diterbitkan bersama halaman-halaman ini: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Masukkan saja ke generator kode, klien API, atau perkakas AI-mu.

Base URL dan autentikasi

Semua metode ada di https://crypto.tgpaybot.com/pay/api/<methodName>.

Autentikasi tiap permintaan dengan token di header TgCryptoPay-API-Token (Crypto-Pay-API-Token diterima sebagai alias kompatibilitas; kalau dua-duanya dikirim, yang kanonik yang menang). Token yang hilang, tidak valid, atau sudah dicabut — juga token milik aplikasi yang sudah dihapus — mengembalikan 401 unauthorized.

Tokennya berbentuk <app_id>:<secret> dan hanya ditampilkan sekali, saat dibuat atau diganti; server cuma menyimpan hash-nya. Lihat Mulai sebagai developer.

Token dan scope

Ada dua jenis kredensial, keduanya diautentikasi dengan cara yang sama:

• Token utama — akses penuh ke semua metode, dan satu-satunya kunci yang menandatangani webhook.
• Token terbatas (ekstensi) — maksimal 10 aktif per aplikasi, dibuat di Lainnya → Merchant API pada bagian Token terbatas, masing-masing punya label dan sebagian scope saja. Mencabut satu token berlaku seketika dan tidak memengaruhi yang lain; mengganti token utama juga tidak memengaruhi token terbatas.

Scope	Metode yang dibuka
(token valid apa pun)	getMe, getCurrencies, getExchangeRates
read	getBalance, getStats, getInvoices, getChecks, getTransfers, getSubscriptionPlans, getSubscriptions
invoices	createInvoice, deleteInvoice
refunds	refundInvoice
payouts	transfer, transferBatch
checks	createCheck, deleteCheck
subscriptions	createSubscriptionPlan, archiveSubscriptionPlan, cancelSubscription

Scope bersifat kumulatif dan berdiri sendiri — invoices tidak otomatis memberi read, jadi server yang cuma membuat faktur boleh memegang token yang tidak bisa membaca apa pun. Memanggil metode yang tidak dicakup tokennya mengembalikan 403 scope_required. getMe melaporkan scopes token yang sedang dipakai (null untuk token utama) dan token_name, jadi kamu selalu bisa memeriksa token apa yang sedang kamu pegang.

Permintaan dan respons

• Metode baca memakai GET dengan parameter di query string. Metode yang memindahkan uang hanya POST — parameternya sebagai body JSON, form-urlencoded, atau query param (kalau bentrok, body yang menang); multipart/form-data ditolak.
• Semua respons berupa JSON dengan envelope yang sama: sukses {"ok": true, "result": …}, error {"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}. Pakai error.name untuk percabangan — itu string stabil yang bisa dibaca mesin.
• Satu kasus khusus: nilai query bertipe salah di metode GET (misalnya offset=abc) mengembalikan HTTP 422 dengan body {"detail": …} di luar envelope. Kirim nilai query dengan tipe yang benar.

Jumlah

• Jumlah kripto berupa string desimal dalam satuan koin utuh ("10.5") — jangan pernah angka JSON. Respons juga membawa amount_minor (ekstensi): nilai satuan terkecil sebagai string bilangan bulat, karena bilangan sebesar wei melebihi kapasitas Number di JavaScript.
• Nilai decimals tiap aset datang dari getCurrencies — hitung jumlahnya dari situ, jangan ditulis sebagai konstanta di kode.
• Jumlah fiat maksimal 2 angka di belakang koma.
• Kurs berupa string fixed-point, bukan angka.

Paginasi

Metode daftar (getInvoices, getChecks, getTransfers, getSubscriptions) menerima offset (bawaan 0) dan count (bawaan 100, maksimal 1000; getSubscriptions maksimal 500) lalu mengembalikan {"items": […]}, diurutkan dari yang terbaru. Filter ID (invoice_ids, check_ids, transfer_ids) berupa daftar bilangan bulat yang dipisah koma. Semua timestamp berupa string ISO 8601.

Idempotensi: spend_id

Metode yang memindahkan uang menerima kunci spend_id yang kamu buat sendiri (1–64 karakter): wajib di transfer dan di tiap item transferBatch, opsional di createCheck dan refundInvoice (ekstensi — pakai saja). Mengulang dengan kunci dan parameter yang sama akan mengulang hasil aslinya, bukan memindahkan dana dua kali, jadi permintaan yang kena timeout selalu aman diulang. Kunci yang sama dengan parameter berbeda mengembalikan 409 idempotency_conflict; percobaan ulang sementara yang asli masih berjalan mengembalikan 409 idempotency_in_progress.

Batas frekuensi

Per aplikasi, dihitung gabungan untuk semua tokennya; kalau terlampaui akan mengembalikan 429 rate_limited:

Metode	Batas
createInvoice, createCheck	60 per menit
refundInvoice, transfer	30 per menit
transferBatch	10 per menit

Metode baca tidak dibatasi frekuensinya. Saat platform sedang pemeliharaan, metode tulis mengembalikan 503 maintenance sementara metode baca tetap jalan.

Metode katalog dan akun

getMe

GET /pay/api/getMe — tanpa parameter. Mengembalikan identitas aplikasinya: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (tipe webhook tambahan yang diaktifkan aplikasinya), plus field introspeksi token scopes / token_name yang dijelaskan di atas.

getBalance

GET /pay/api/getBalance — tanpa parameter. Mengembalikan array berisi satu baris per aset yang didukung, termasuk yang saldonya kosong: currency_code, available (saldo yang bisa dipakai), onhold (dana yang terkunci di cek kripto yang masih beredar), dan amount_minor.

getCurrencies

GET /pay/api/getCurrencies — tanpa parameter. Daftar resmi apa saja yang didukung API: baris kripto (is_blockchain: true) dan mata uang fiat yang bisa dipakai untuk memberi harga faktur (is_fiat: true). Tiap baris membawa code, name, decimals, dan flag is_stablecoin.

getExchangeRates

GET /pay/api/getExchangeRates — tanpa parameter. Kurs kripto ke fiat: source, target, rate (string fixed-point), dan is_valid — false berarti seluruh tabelnya disajikan dari cache lama; anggap kurs itu sebagai indikasi saja.

getStats

GET /pay/api/getStats — start_at / end_at opsional (ISO 8601; rentang bawaannya 24 jam terakhir). Mengembalikan volume (nilai USD faktur yang dibayar dalam rentang itu), conversion (dibayar/dibuat, dalam persen), unique_users_count, created_invoice_count, paid_invoice_count, dan batas rentang yang benar-benar dipakai. Tanggal yang tidak bisa diurai mengembalikan 400 invalid_date.

Error yang bisa muncul di semua metode

HTTP	error.name	Kapan
401	unauthorized	token hilang, tidak valid, atau sudah dicabut
403	scope_required	token tidak punya scope untuk metode itu
400	invalid_request	parameter tidak bisa diurai atau tidak valid (POST)
429	rate_limited	batas frekuensi terlampaui
503	maintenance	platform sedang dalam pemeliharaan (metode tulis)
500	internal_error	error server yang tidak terduga

Error khusus tiap metode dicantumkan di halaman metodenya masing-masing.