Referensi API

URL dasar

Produksi

https://cryptomerchant.online/api/v1https://cryptomerchant.online/api/v1

Pengembangan lokal

http://localhost:3000/api/v1http://localhost:3000/api/v1

Deskripsi API ini yang dapat dibaca mesin ada di /openapi.json (OpenAPI 3.1). Anda dapat mengimpornya ke Postman atau generator klien.

Autentikasi

Kirim kunci rahasia Anda di header Authorization pada setiap permintaan, sebagai token Bearer. Buat kunci di portal di bagian Developer.

Authorization: Bearer cm_live_…

• Kunci diawali dengan cm_live_ di mainnet dan cm_test_ di testnet.
• Kunci lengkap hanya ditampilkan sekali, saat Anda membuatnya. Kami hanya menyimpan hash-nya, jadi simpan kunci di tempat yang aman.
• Gunakan kunci hanya di server Anda. Jangan pernah menaruhnya di halaman web, aplikasi seluler, atau repositori kode publik.
• Jika kunci mungkin bocor, cabut di portal dan buat kunci baru.

Error

Saat permintaan gagal, respons memiliki status error HTTP dan body JSON dengan code yang dapat dibaca mesin dan message yang dapat dibaca manusia:

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

Status HTTP

400

Permintaan tidak valid, misalnya ada field yang hilang atau jumlah yang terlalu kecil.

401

Kunci API tidak ada, salah, atau sudah dicabut.

403

Akun Anda tidak dapat melakukan ini: belum aktif, atau sedang ditangguhkan.

404

Objek tidak ada, atau milik bisnis lain.

409

Invoice tidak dapat melakukan ini dalam statusnya saat ini, misalnya membatalkan invoice yang sudah menerima pembayaran.

500

Terjadi kesalahan di pihak kami. Coba lagi beberapa saat kemudian.

Kode yang mungkin Anda temui

invalid_json

Body permintaan bukan objek JSON.

invalid_request

Ada field yang hilang atau tidak valid. Pesan error menyebutkan field tersebut.

unauthorized

Kunci API tidak ada, salah, atau sudah dicabut.

account_suspended

Akun merchant ini ditangguhkan.

merchant_not_live

Akun Anda belum aktif. Selesaikan penyiapan di portal terlebih dahulu.

invalid_amount

Jumlah tidak ada, bukan angka, atau tidak lebih besar dari nol.

amount_too_small

Nilai jumlah tersebut kurang dari 0,50 dolar AS.

invalid_asset

ID koin bukan koin yang dikenal.

asset_not_accepted

Anda tidak menerima koin tersebut.

invalid_state

Invoice tidak dapat melakukan ini dalam statusnya saat ini.

not_found

Tidak ada objek dengan ID tersebut.

server_error

Terjadi kesalahan di pihak kami.

Objek invoice

Invoice memiliki bentuk ini di respons API dan di webhook. Jumlah berupa string desimal, sehingga presisinya tidak hilang.

idstring

ID invoice, diawali dengan inv_.

objectstring

Selalu invoice.

statusstring

Status saat ini. Lihat daftar status di bawah.

amountstring

Harga yang Anda minta, dalam currency.

currencystring

Mata uang harga, misalnya USD.

amount_usdstring

Harga dalam dolar AS.

descriptionstring | null

Deskripsi Anda, ditampilkan kepada pelanggan.

order_idstring | null

Referensi pesanan Anda sendiri.

customer_emailstring | null

Email pelanggan, jika Anda memberikannya.

metadataobject

Objek yang Anda kirim saat membuat invoice, dikembalikan tanpa perubahan.

coinobject | null

Koin yang dipilih pelanggan, atau koin yang benar-benar mereka gunakan untuk membayar, dengan id, symbol, dan network-nya. null sampai koin dipilih.

requested_coinobject | null

Biasanya null. Jika pelanggan membayar dengan koin lain atau di jaringan lain dan pembayaran tersebut dihitung, ini adalah koin yang diminta invoice, dengan field yang sama seperti coin. Lihat koin yang salah atau jaringan yang salah.

pay_addressstring | null

Alamat deposit untuk invoice ini. null sampai koin dipilih.

pay_amountstring | null

Jumlah tepat yang harus dikirim, dalam koin yang dipilih.

network_fee_amountstring

Bagian dari pay_amount: biaya gas yang dibayar pelanggan di atas harga, dalam koin. 0 jika tidak ada.

network_fee_usdstring

Biaya gas yang sama dalam dolar AS.

rate_usdstring | null

Harga yang dikunci untuk satu unit koin yang dipilih, dalam dolar AS.

received_amountstring

Jumlah yang sudah diterima sejauh ini, dalam koin yang dipilih.

received_usdstring

Nilai dolar AS dari jumlah yang sudah diterima.

overpaid_amountstring

Kelebihan yang dibayarkan di atas jumlah invoice, dalam koin yang dipilih.

refunded_amountstring

Berapa banyak yang telah Anda kembalikan pada pembayaran ini dengan link pengembalian dana, dalam koin yang dibayarkan. 0 jika tidak ada.

checkout_urlstring

Halaman invoice. Arahkan pelanggan Anda ke sini untuk membayar.

redirect_urlstring | null

Tujuan pelanggan setelah membayar.

expires_atISO 8601

Waktu invoice kedaluwarsa jika tidak ada pembayaran yang terdeteksi.

paid_atISO 8601 | null

Waktu invoice dibayar, atau null.

created_atISO 8601

Waktu invoice dibuat.

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Status invoice

openTerbuka

Dibuat. Pelanggan belum memilih koin.

awaiting_paymentMenunggu pembayaran

Koin sudah dipilih, alamat deposit sudah ditetapkan, dan kurs sudah dikunci.

confirmingMengonfirmasi

Pembayaran terdeteksi on-chain dan sedang menunggu konfirmasi.

underpaidKurang bayar

Pembayaran yang dikonfirmasi kurang lebih dari toleransi Anda. Pelanggan dapat membayar sisanya atau meminta pengembalian dana.

paidLunas

Lunas dan dikonfirmasi. Jumlahnya, dikurangi biaya, sudah masuk ke saldo Anda. Pengembalian dana sebagian tidak mengubah status ini.

expiredKedaluwarsa

Waktu habis sebelum ada pembayaran yang terdeteksi.

cancelledDibatalkan

Invoice dibatalkan sebelum ada pembayaran yang terdeteksi.

refundedDikembalikan

Pelanggan menerima pengembalian atas jumlah yang mereka kirim pada invoice kurang bayar, atau Anda mengembalikan seluruh jumlah yang Anda terima dari invoice yang lunas.

Membuat invoice

POST/invoices

Membuat invoice dan mengembalikan objek invoice dengan status 201. Arahkan pelanggan Anda ke checkout_url-nya.

Parameter body

amountWajibnumber | string

Harga, sebagai angka atau string desimal. Nilainya minimal harus 0,50 dolar AS.

currencyOpsionalstring

Mata uang harga, misalnya USD. Default-nya USD.

descriptionOpsionalstring

Apa yang dibayar pelanggan, maksimal 300 karakter. Ditampilkan di halaman invoice.

order_idOpsionalstring

Referensi pesanan Anda sendiri, maksimal 120 karakter, untuk mencocokkan invoice dengan pesanan.

customer_emailOpsionalstring

Alamat email pelanggan. Pembayaran dikelompokkan per pelanggan di portal.

customer_nameOpsionalstring

Nama pelanggan, maksimal 120 karakter.

redirect_urlOpsionalstring

URL lengkap tujuan pelanggan setelah membayar.

metadataOpsionalobject

Objek JSON apa pun hingga 4 KB. Dikembalikan tanpa perubahan di invoice dan di webhook.

coinOpsionalstring

Pilih koin di awal berdasarkan ID-nya, misalnya USDT.TRON. Koin harus termasuk dalam koin yang diterima Anda.

Dengan coin yang dipilih di awal, alamat deposit langsung ditetapkan dan kurs langsung dikunci, sehingga pay_address dan pay_amount sudah terisi dan Anda dapat menampilkan detail pembayaran di antarmuka Anda sendiri.

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Daftar invoice

GET/invoices

Mengembalikan invoice Anda, dari yang terbaru, satu halaman setiap kali.

Parameter query

statusOpsionalstring

Hanya invoice dengan status ini, misalnya paid. Harus salah satu status di atas.

limitOpsionalnumber

Jumlah invoice yang dikembalikan, dari 1 hingga 100. Default-nya 20.

starting_afterOpsionalstring

ID invoice. Mengembalikan invoice setelahnya, untuk halaman berikutnya.

Invoice ada di data. Jika has_more bernilai true, minta halaman berikutnya dengan starting_after berisi ID invoice terakhir yang Anda terima.

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Mengambil invoice

GET/invoices/{id}

Mengembalikan satu invoice berdasarkan ID-nya.

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Membatalkan invoice

POST/invoices/{id}/cancel

Membatalkan invoice. Ini hanya berfungsi selama invoice belum dibayar dan belum ada pembayaran yang terdeteksi untuknya.

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Saldo

GET/balances

Mengembalikan jumlah yang dimiliki bisnis Anda dalam setiap koin, totalnya dalam dolar AS, dan saldo gas Anda.

data[].coin

ID koin, misalnya USDT.TRON.

data[].symbol

Simbol koin, misalnya USDT.

data[].network

Jaringan tempat koin berada.

data[].amount

Jumlah koin yang Anda miliki, sebagai string desimal.

data[].usd

Nilainya dalam dolar AS dengan harga saat ini.

total_usd

Nilai semua koin Anda dalam dolar AS.

gas_balance_usd

Saldo gas Anda dalam dolar AS, digunakan untuk membayar biaya gas.

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Koin yang diterima

GET/coins

Mengembalikan koin yang Anda terima saat ini, masing-masing dengan id, symbol, name, network, dan decimals. Gunakan id sebagai coin saat Anda membuat invoice. Contoh:

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Membuat link pembayaran

POST/payment-links

Membuat link pembayaran dan mengembalikannya dengan status 201, termasuk id dan url yang dapat dibagikan.

Parameter body

titleWajibstring

Nama barang atau layanan yang dibayar pelanggan, maksimal 120 karakter.

amountOpsionalnumber | string

Harga tetap. Hilangkan field ini agar pelanggan memasukkan jumlahnya sendiri.

currencyOpsionalstring

Mata uang harga. Default-nya USD.

descriptionOpsionalstring

Detail tambahan yang ditampilkan kepada pelanggan, maksimal 300 karakter.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Daftar link pembayaran

GET/payment-links

Mengembalikan 100 link pembayaran terbaru Anda, dari yang terbaru, di data.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Objek pencairan

Webhook pencairan (payout.sent dan payout.failed) membawa objek ini di data. Pencairan bagian mitra dari bagi hasil menggunakan objek yang sama, dengan partner_share bernilai true.

idstring

ID pencairan.

objectstring

Selalu payout.

coinstring

ID koin, misalnya USDT.TRON.

amountstring

Jumlah yang dicairkan, dalam koin tersebut.

network_feestring

Biaya gas untuk mengirimnya, dalam koin tersebut.

to_addressstring

Alamat dompet tujuan pengiriman.

statusstring

queued, running, done, atau failed.

tx_hashstring | null

ID transaksi di blockchain, setelah dikirim.

autoboolean

true jika pencairan dilakukan secara otomatis, bukan diminta oleh seseorang.

partner_shareboolean

true jika pencairan ini adalah bagian mitra dari bagi hasil, yang dikirim ke dompet mitra.

created_atISO 8601

Waktu pencairan dibuat.

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}