API pemeriksaan transaksi

Periksa transaksi sebelum mengonfirmasi pembayaran

ChainZap membantu Anda memahami apa yang terjadi pada transaksi dan apakah datanya cukup untuk alur pembayaran Anda. API mengembalikan rincian transfer, penilaian risiko, dan pencocokan dengan rincian pembayaran jika diminta.

Fitur yang tersedia

Versi v1 mendukung TRON. Dukungan Ethereum dan TON masih direncanakan; API belum menerima permintaan untuk kedua jaringan tersebut. Akses diberikan melalui undangan, dengan batas penggunaan untuk setiap organisasi.

• POST /v1/transaction/check: periksa transaksi berdasarkan hash.
• GET /v1/usage: lihat batas dan statistik penggunaan.

Kirim permintaan dari server Anda dengan kunci pada header X-API-Key.

Baca seluruh hasil

HTTP 200 berarti permintaan berhasil diproses. Kode ini saja tidak membuktikan bahwa pembayaran sudah diterima atau bebas risiko.

Baca transaction_state, overall_state, coverage, hasil pencocokan, freshness, dan reasons bersama-sama. Nilai null dapat berarti data tidak tersedia atau perbandingan tidak diminta, bergantung pada kolomnya. Data yang tidak tersedia tidak boleh dianggap sebagai hasil pemeriksaan yang baik.

Mulai dari permintaan pertama, lalu pelajari kelengkapan data dan pengulangan permintaan.

Kirim permintaan pertama

Dapatkan akses

Hubungi dukungan ChainZap untuk membahas akses dan mendapatkan undangan. Setelah masuk ke portal, buka Kunci API, buat kunci dengan nama yang jelas, lalu simpan di penyimpanan rahasia server. Kunci lengkap hanya ditampilkan sekali.

Periksa transaksi berdasarkan hash

Contoh berikut menggunakan kunci dan hash fiktif. Ganti keduanya di server Anda. Simpan Idempotency-Key bersama data operasi sebelum mengirim permintaan agar dapat digunakan kembali saat mencoba ulang.

curl --include --max-time 15 'https://api.chainzap.io/v1/transaction/check' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: cz_live_000000000000.fictional_example_only' \
  -H 'Idempotency-Key: merchant-order-1001-check-1' \
  -H 'X-Request-ID: merchant-order-1001-attempt-1' \
  --data '{"network":"tron","tx_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'

Simpan X-Request-ID dari header respons. Nilainya sama dengan request_id pada JSON dan membantu tim dukungan menemukan permintaan Anda. Hash fiktif dapat menghasilkan not_found; lihat status transaksi.

Cocokkan dengan rincian pembayaran

Tambahkan penerima, kontrak token, dan jumlah yang diharapkan jika Anda perlu memastikan transaksi sesuai dengan pembayaran tertentu.

{
  "network": "tron",
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "expected_recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "expected_token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "expected_amount": "1250.000001"
}

Alamat dalam contoh bukan tujuan pengiriman dana. Identitas token ditentukan oleh alamat kontrak. Jumlah dikirim sebagai string dengan titik sebagai pemisah desimal. Ketiga hasil pencocokan mengacu pada transfer terpilih yang sama. Lihat pencocokan pembayaran.

Jika respons tidak diterima

Kirim ulang isi permintaan dan Idempotency-Key yang sama. Jangan membuat kunci baru hanya karena koneksi terputus: permintaan pertama mungkin sudah diproses.

Jika respons berisi kesalahan, ulangi hanya bila error.retryable=true, patuhi Retry-After, dan batasi jumlah percobaan. Kesalahan yang sudah disimpan dapat dikembalikan lagi tanpa pemeriksaan sumber data baru.

Lihat contoh Python dan TypeScript untuk pola pengulangan yang dibatasi, serta statistik penggunaan untuk sisa kuota.

Akses dan kunci API

Gunakan kunci hanya dari server

Sertakan X-API-Key pada setiap permintaan API dan gunakan HTTPS. Jangan memasukkan kunci ke URL, kode frontend, penyimpanan browser, analitik, Git, atau pesan dukungan.

Satu kunci memberikan akses ke satu organisasi. Permintaan tidak dapat memilih organisasi lain melalui isi JSON. Sesi masuk portal terpisah dari autentikasi menggunakan kunci API.

Anggota dengan peran owner, admin, dan developer dapat membuat, mengganti, serta mencabut kunci. Peran billing dan viewer dapat melihat statistik dan informasi kunci, tetapi tidak dapat mengelola kunci atau menjalankan pemeriksaan.

Membuat, mengganti, dan mencabut kunci

Gunakan kunci dengan nama yang jelas untuk setiap integrasi. Kunci lengkap hanya ditampilkan saat dibuat atau diganti. Daftar kunci menampilkan awalannya saja.

Penggantian langsung mencabut kunci lama dan membuat kunci baru dalam satu operasi. Perbarui konfigurasi server setelahnya. Untuk perpindahan terencana tanpa jeda layanan, buat kunci terpisah terlebih dahulu, pindahkan integrasi dan pastikan berfungsi, lalu cabut kunci sebelumnya.

Kesalahan akses

• 401 invalid_api_key: kunci tidak valid atau sudah dicabut.
• 403 tenant_suspended: akses organisasi ditangguhkan.
• 403 network_not_enabled: jaringan tidak diaktifkan untuk organisasi.

Perbaiki akses sebelum mencoba ulang. Mengulang permintaan yang sama tanpa perubahan tidak akan menyelesaikan masalah ini.

Periksa satu transaksi

POST /v1/transaction/check

Kirim objek JSON dengan kolom wajib network dan tx_hash. Kolom yang tidak dikenal akan ditolak.

Alamat harus memiliki checksum TRON yang valid. Jumlah tidak boleh negatif. Angka JSON dan notasi eksponen seperti 1e3 tidak diterima. Isi permintaan dibatasi hingga 4 KiB.

Sertakan Content-Type: application/json, X-API-Key dari server, dan Idempotency-Key untuk pengulangan aman. Gunakan X-Request-ID untuk menghubungkan permintaan dengan catatan operasi Anda. Tipe dan kolom lengkap tersedia di referensi API.

Isi respons

Respons mencakup status dan konfirmasi transaksi, daftar transfer, transfer terpilih, risiko, pemeriksaan sanksi, keaslian token, pencocokan pembayaran, serta kelengkapan dan waktu data. reasons memuat 2-5 penjelasan yang diprioritaskan.

Baca transaction_state terpisah dari overall_state. Tangani nilai null secara eksplisit. Jumlah transfer dan persentase paparan risiko disajikan sebagai string.

transfers_truncated=true berarti daftar transfer telah dipersingkat. AMBIGUOUS_TRANSFER berarti lebih dari satu transfer cocok dengan syarat pembayaran. Keduanya perlu diperhatikan. Jangan menganggap daftar yang dipersingkat sudah lengkap atau menggabungkan hasil pencocokan dari transfer berbeda.

Penggunaan kuota

Pemeriksaan dengan data lengkap memakai satu unit kuota bulanan, termasuk jika hasilnya berisiko tinggi. Data tidak lengkap tidak mengurangi kuota. Pengembalian ulang hasil operasi yang sama tidak memakai kuota dua kali.

Cocokkan transfer dengan rincian pembayaran

Gunakan kolom expected_* untuk memeriksa penerima, kontrak token, dan jumlah pembayaran tertentu. Anda dapat mengirim semua kolom atau hanya yang diperlukan.

Semua perbandingan mengacu pada satu transfer

Satu transaksi dapat berisi beberapa transfer. ChainZap memprioritaskan transfer yang memenuhi seluruh syarat. Jika tidak ada, layanan memilih transfer dengan kecocokan terbanyak. Jika hasilnya sama, indeks transfer menentukan pilihan secara konsisten.

recipient_match, token_match, dan amount_match selalu mengacu pada transfer terpilih tersebut. Jika beberapa transfer memenuhi seluruh syarat, respons memuat AMBIGUOUS_TRANSFER.

Cara nilai dibandingkan

Jika Anda memberikan nilai yang diharapkan tetapi data transfer belum tersedia, kolom perbandingan terkait bernilai null, cakupan menjadi partial, dan respons menyertakan alasan EXPECTED_DATA_UNAVAILABLE. Misalnya, tanpa jumlah desimal token, API tidak dapat menyatakan bahwa jumlahnya berbeda. Jangan menganggap null sebagai kecocokan yang terkonfirmasi.

Penerima diperiksa berdasarkan alamat TRON dengan checksum yang valid. Token dibandingkan berdasarkan alamat kontrak, bukan nama atau simbolnya. Simbol yang sama tidak membuktikan bahwa tokennya sama.

Jumlah harus berupa string desimal, misalnya "10.000001". Layanan mengubahnya menjadi bilangan bulat dalam satuan terkecil token dan membandingkannya secara tepat, tanpa toleransi pembulatan. Presisi yang tidak sesuai dengan jumlah desimal aset menghasilkan 422 invalid_expected_amount.

Contoh ketidakcocokan

Anda mengharapkan "10.000001", tetapi transfer terpilih berjumlah "10". Respons berisi amount_match=false dan EXPECTED_AMOUNT_MISMATCH.

Penerima yang berbeda menghasilkan EXPECTED_RECIPIENT_MISMATCH. Kontrak token yang berbeda menghasilkan EXPECTED_TOKEN_MISMATCH. Jumlah yang cocok tidak membuktikan bahwa penerima dan token juga cocok. Sebelum mengonfirmasi pembayaran, periksa seluruh perbandingan yang diperlukan, status transaksi, dan penilaian keseluruhan.

Batas dan statistik penggunaan

GET /v1/usage

Permintaan ini mengembalikan batas dan statistik organisasi pemilik kunci API.

curl --include --max-time 15 'https://api.chainzap.io/v1/usage?days=30' \
  -H 'X-API-Key: cz_live_000000000000.fictional_example_only' \
  -H 'X-Request-ID: merchant-usage-1001'

Parameter days menentukan periode statistik antara 1 dan 90 hari, dengan nilai bawaan 30. Permintaan ini tidak memerlukan Idempotency-Key. Membaca statistik tetap terkena batas frekuensi, tetapi tidak memakai kuota pemeriksaan transaksi.

Kuota bulan berjalan

period.start dan period.end menandai awal dan akhir bulan kalender berdasarkan UTC.

Jika permintaan selesai tanpa tagihan, kuota yang dicadangkan dilepas. Seluruh kunci dan permintaan dari portal menggunakan kuota organisasi yang sama.

Statistik periode pilihan

recent menghitung pemeriksaan selesai dalam days hari terakhir. Pengembalian ulang respons tersimpan tidak membuat catatan pemeriksaan baru. Statistik mencakup jumlah permintaan, pemeriksaan yang memakai kuota, kesalahan, hasil LIMITED_DATA, waktu respons rata-rata, serta distribusi jaringan dan penilaian keseluruhan.

Hash transaksi dan rincian penyedia tidak disertakan. Portal juga menyediakan statistik harian UTC serta p50/p95 jika terdapat setidaknya 20 pemeriksaan selesai dalam 30 hari terakhir. Respons HTTP yang berhasil dapat memiliki data tidak lengkap; hitungan ini merupakan bagian dari total respons, bukan tambahan terpisah.

Contoh integrasi

Python: percobaan ulang dengan kunci yang sama

Contoh untuk server ini menggunakan httpx. Kunci API yang ditampilkan adalah contoh fiktif. Dalam integrasi sebenarnya, ambil kunci dari penyimpanan rahasia server. Simpan operation_key dan body dalam catatan operasi sebelum percobaan pertama, lalu gunakan kembali keduanya setelah proses dimulai ulang.

import random
import time
import httpx

api_key = "cz_live_000000000000.fictional_example_only"
operation_key = "merchant-order-1001-check-1"
body = {"network": "tron", "tx_hash": "a" * 64}


def check():
    with httpx.Client(timeout=15, follow_redirects=False) as client:
        for attempt in range(4):
            try:
                response = client.post(
                    "https://api.chainzap.io/v1/transaction/check",
                    headers={
                        "X-API-Key": api_key,
                        "Idempotency-Key": operation_key,
                        "X-Request-ID": f"order-1001-attempt-{attempt + 1}",
                    },
                    json=body,
                )
            except httpx.TransportError:
                if attempt == 3:
                    raise RuntimeError("unresolved_transport_outcome") from None
                time.sleep(2 ** attempt + random.uniform(0, 1))
                continue
            print("X-Request-ID:", response.headers.get("X-Request-ID"))
            try:
                result = response.json()
            except ValueError:
                raise RuntimeError("unresolved_gateway_response") from None
            if response.is_success:
                return result
            error = result.get("error", {})
            if error.get("retryable") is not True:
                raise RuntimeError(error.get("code", "unresolved_response"))
            if response.headers.get("Idempotent-Replayed") == "true":
                raise RuntimeError("stored_error_requires_reconciliation")
            try:
                instructed = int(response.headers.get("Retry-After", "0"))
            except ValueError:
                raise RuntimeError("invalid_retry_after") from None
            delay = max(instructed, 2 ** attempt) + random.uniform(0, 1)
            if attempt == 3 or delay > 30:
                raise RuntimeError("schedule_retry_with_same_operation_key")
            time.sleep(delay)

Kode ini menangani galat sementara dan gangguan jaringan tanpa membuat operasi baru. Tentukan tindakan bisnis berdasarkan hasil pemeriksaan. Jangan mencatat body atau seluruh respons dalam log.

JavaScript / TypeScript: permintaan dari server

Jalankan kode ini di server. Jangan memasukkan kunci aktif ke dalam browser. Seperti pada contoh Python, simpan kunci operasi dan isi permintaan sebelum memanggil fungsi.

type PublicResult = {
  request_id?: string;
  error?: { code: string; message: string; retryable: boolean };
  [field: string]: unknown;
};

const apiKey = "cz_live_000000000000.fictional_example_only";
const operationKey = "merchant-order-1001-check-1";
const body = { network: "tron", tx_hash: "a".repeat(64) };
const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

async function check(): Promise<PublicResult> {
  for (let attempt = 0; attempt < 4; attempt++) {
    let response: Response;
    try {
      response = await fetch("https://api.chainzap.io/v1/transaction/check", {
        method: "POST", redirect: "error", signal: AbortSignal.timeout(15000),
        headers: {
          "Content-Type": "application/json", "X-API-Key": apiKey,
          "Idempotency-Key": operationKey,
          "X-Request-ID": `order-1001-attempt-${attempt + 1}`,
        },
        body: JSON.stringify(body),
      });
    } catch {
      if (attempt === 3) throw new Error("unresolved_transport_outcome");
      await wait((2 ** attempt + Math.random()) * 1000);
      continue;
    }
    console.info("X-Request-ID:", response.headers.get("X-Request-ID"));
    const result = await response.json() as PublicResult;
    if (response.ok) return result;
    if (result.error?.retryable !== true) {
      throw new Error(result.error?.code ?? "unresolved_response");
    }
    if (response.headers.get("Idempotent-Replayed") === "true") {
      throw new Error("stored_error_requires_reconciliation");
    }
    const instructed = Number(response.headers.get("Retry-After") ?? "0");
    if (!Number.isFinite(instructed) || instructed < 0) {
      throw new Error("invalid_retry_after");
    }
    const delay = Math.max(instructed, 2 ** attempt) + Math.random();
    if (attempt === 3 || delay > 30) {
      throw new Error("schedule_retry_with_same_operation_key");
    }
    await wait(delay * 1000);
  }
  throw new Error("retry_budget_exhausted");
}

Contoh respons

Data berikut dibuat untuk menunjukkan struktur respons, bukan hasil pemeriksaan langsung. Setiap contoh memiliki header X-Request-ID yang sama dengan request_id. Perhatikan nilai null, kelengkapan data, dan penilaian keseluruhan.

Transaksi terkonfirmasi

{
  "aml_risk_level": "low",
  "amount": "1250.000001",
  "amount_match": true,
  "confirmations": 27,
  "coverage": "complete",
  "decimals": 6,
  "freshness": {
    "checked_at": "2026-09-03T12:00:00Z",
    "max_source_age_seconds": 4,
    "risk_data_at": "2026-09-03T12:00:00Z",
    "token_data_at": "2026-09-03T12:00:00Z",
    "transaction_at": "2026-09-03T11:59:00Z"
  },
  "key_exposure": [],
  "network": "tron",
  "overall_state": "CLEAR",
  "reasons": [
    {
      "category": "transaction",
      "code": "TX_FINALIZED",
      "severity": "info"
    },
    {
      "category": "risk",
      "code": "AML_LOW",
      "severity": "info"
    }
  ],
  "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "recipient_match": true,
  "request_id": "example-confirmed",
  "required_confirmations": 19,
  "sanctions_hit": false,
  "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "token_authenticity": "official",
  "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "token_match": true,
  "token_symbol": "USDT",
  "transaction_category": "trc20_transfer",
  "transaction_state": "confirmed",
  "transaction_type": "TriggerSmartContract",
  "transfers": [
    {
      "amount": "1250.000001",
      "asset_type": "trc20",
      "decimals": 6,
      "index": 0,
      "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "token_id": null,
      "token_symbol": "USDT"
    }
  ],
  "transfers_truncated": false,
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Menunggu konfirmasi

{
  "aml_risk_level": "low",
  "amount": "1250.000001",
  "amount_match": true,
  "confirmations": 3,
  "coverage": "complete",
  "decimals": 6,
  "freshness": {
    "checked_at": "2026-09-03T12:00:00Z",
    "max_source_age_seconds": 4,
    "risk_data_at": "2026-09-03T12:00:00Z",
    "token_data_at": "2026-09-03T12:00:00Z",
    "transaction_at": "2026-09-03T11:59:00Z"
  },
  "key_exposure": [],
  "network": "tron",
  "overall_state": "REVIEW",
  "reasons": [
    {
      "code": "TX_PENDING_CONFIRMATIONS",
      "category": "transaction",
      "severity": "warning"
    },
    {
      "code": "AML_LOW",
      "category": "risk",
      "severity": "info"
    }
  ],
  "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "recipient_match": true,
  "request_id": "example-pending",
  "required_confirmations": 19,
  "sanctions_hit": false,
  "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "token_authenticity": "official",
  "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "token_match": true,
  "token_symbol": "USDT",
  "transaction_category": "trc20_transfer",
  "transaction_state": "pending",
  "transaction_type": "TriggerSmartContract",
  "transfers": [
    {
      "amount": "1250.000001",
      "asset_type": "trc20",
      "decimals": 6,
      "index": 0,
      "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "token_id": null,
      "token_symbol": "USDT"
    }
  ],
  "transfers_truncated": false,
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Transaksi gagal

{
  "aml_risk_level": "low",
  "amount": null,
  "amount_match": null,
  "confirmations": 27,
  "coverage": "complete",
  "decimals": 6,
  "freshness": {
    "checked_at": "2026-09-03T12:00:00Z",
    "max_source_age_seconds": 4,
    "risk_data_at": "2026-09-03T12:00:00Z",
    "token_data_at": "2026-09-03T12:00:00Z",
    "transaction_at": "2026-09-03T11:59:00Z"
  },
  "key_exposure": [],
  "network": "tron",
  "overall_state": "REVIEW",
  "reasons": [
    {
      "code": "TX_REVERTED",
      "category": "transaction",
      "severity": "warning"
    },
    {
      "code": "TX_FACTS_VERIFIED",
      "category": "transaction",
      "severity": "info"
    }
  ],
  "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "recipient_match": null,
  "request_id": "example-failed",
  "required_confirmations": 19,
  "sanctions_hit": false,
  "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "token_authenticity": "official",
  "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "token_match": null,
  "token_symbol": "USDT",
  "transaction_category": "trc20_transfer",
  "transaction_state": "failed",
  "transaction_type": "TriggerSmartContract",
  "transfers": [],
  "transfers_truncated": false,
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Transaksi tidak ditemukan

{
  "aml_risk_level": "unknown",
  "amount": null,
  "amount_match": null,
  "confirmations": null,
  "coverage": "complete",
  "decimals": null,
  "freshness": {
    "checked_at": "2026-09-03T12:00:00Z",
    "max_source_age_seconds": 4,
    "risk_data_at": "2026-09-03T12:00:00Z",
    "token_data_at": "2026-09-03T12:00:00Z",
    "transaction_at": "2026-09-03T11:59:00Z"
  },
  "key_exposure": [],
  "network": "tron",
  "overall_state": "REVIEW",
  "reasons": [
    {
      "code": "TX_NOT_FOUND",
      "category": "transaction",
      "severity": "warning"
    },
    {
      "code": "TX_FACTS_VERIFIED",
      "category": "transaction",
      "severity": "info"
    }
  ],
  "recipient": null,
  "recipient_match": null,
  "request_id": "example-not-found",
  "required_confirmations": 19,
  "sanctions_hit": null,
  "sender": null,
  "token_authenticity": "unknown",
  "token_contract": null,
  "token_match": null,
  "token_symbol": null,
  "transaction_category": "unknown",
  "transaction_state": "not_found",
  "transaction_type": "unknown",
  "transfers": [],
  "transfers_truncated": false,
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Data belum lengkap

{
  "aml_risk_level": "unknown",
  "amount": "1250.000001",
  "amount_match": true,
  "confirmations": 27,
  "coverage": "partial",
  "decimals": 6,
  "freshness": {
    "checked_at": "2026-09-03T12:00:00Z",
    "max_source_age_seconds": 4,
    "risk_data_at": "2026-09-03T12:00:00Z",
    "token_data_at": "2026-09-03T12:00:00Z",
    "transaction_at": "2026-09-03T11:59:00Z"
  },
  "key_exposure": [],
  "network": "tron",
  "overall_state": "LIMITED_DATA",
  "reasons": [
    {
      "code": "AML_UNAVAILABLE",
      "category": "risk",
      "severity": "warning"
    },
    {
      "code": "SANCTIONS_UNAVAILABLE",
      "category": "sanctions",
      "severity": "warning"
    }
  ],
  "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "recipient_match": true,
  "request_id": "example-limited-data",
  "required_confirmations": 19,
  "sanctions_hit": null,
  "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "token_authenticity": "official",
  "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "token_match": true,
  "token_symbol": "USDT",
  "transaction_category": "trc20_transfer",
  "transaction_state": "confirmed",
  "transaction_type": "TriggerSmartContract",
  "transfers": [
    {
      "amount": "1250.000001",
      "asset_type": "trc20",
      "decimals": 6,
      "index": 0,
      "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "token_id": null,
      "token_symbol": "USDT"
    }
  ],
  "transfers_truncated": false,
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Kecocokan daftar sanksi

{
  "aml_risk_level": "low",
  "amount": "1250.000001",
  "amount_match": true,
  "confirmations": 27,
  "coverage": "complete",
  "decimals": 6,
  "freshness": {
    "checked_at": "2026-09-03T12:00:00Z",
    "max_source_age_seconds": 4,
    "risk_data_at": "2026-09-03T12:00:00Z",
    "token_data_at": "2026-09-03T12:00:00Z",
    "transaction_at": "2026-09-03T11:59:00Z"
  },
  "key_exposure": [],
  "network": "tron",
  "overall_state": "HIGH_RISK",
  "reasons": [
    {
      "code": "SANCTIONS_HIT",
      "category": "sanctions",
      "severity": "critical"
    },
    {
      "code": "TX_FINALIZED",
      "category": "transaction",
      "severity": "info"
    }
  ],
  "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "recipient_match": true,
  "request_id": "example-sanctions-hit",
  "required_confirmations": 19,
  "sanctions_hit": true,
  "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "token_authenticity": "official",
  "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "token_match": true,
  "token_symbol": "USDT",
  "transaction_category": "trc20_transfer",
  "transaction_state": "confirmed",
  "transaction_type": "TriggerSmartContract",
  "transfers": [
    {
      "amount": "1250.000001",
      "asset_type": "trc20",
      "decimals": 6,
      "index": 0,
      "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "token_id": null,
      "token_symbol": "USDT"
    }
  ],
  "transfers_truncated": false,
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Rincian pembayaran tidak cocok

{
  "aml_risk_level": "low",
  "amount": "1250.000001",
  "amount_match": false,
  "confirmations": 27,
  "coverage": "complete",
  "decimals": 6,
  "freshness": {
    "checked_at": "2026-09-03T12:00:00Z",
    "max_source_age_seconds": 4,
    "risk_data_at": "2026-09-03T12:00:00Z",
    "token_data_at": "2026-09-03T12:00:00Z",
    "transaction_at": "2026-09-03T11:59:00Z"
  },
  "key_exposure": [],
  "network": "tron",
  "overall_state": "REVIEW",
  "reasons": [
    {
      "code": "EXPECTED_AMOUNT_MISMATCH",
      "category": "expected",
      "severity": "warning"
    },
    {
      "code": "TX_FINALIZED",
      "category": "transaction",
      "severity": "info"
    }
  ],
  "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "recipient_match": true,
  "request_id": "example-expected-mismatch",
  "required_confirmations": 19,
  "sanctions_hit": false,
  "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "token_authenticity": "official",
  "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "token_match": true,
  "token_symbol": "USDT",
  "transaction_category": "trc20_transfer",
  "transaction_state": "confirmed",
  "transaction_type": "TriggerSmartContract",
  "transfers": [
    {
      "amount": "1250.000001",
      "asset_type": "trc20",
      "decimals": 6,
      "index": 0,
      "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "token_id": null,
      "token_symbol": "USDT"
    }
  ],
  "transfers_truncated": false,
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Status transaksi

transaction_state menjelaskan status transaksi di blockchain. Kolom ini tidak menggantikan penilaian risiko atau kelengkapan data.

Konfirmasi TRON

Versi v1 mensyaratkan 19 konfirmasi bersama bukti finalitas jaringan. Bandingkan confirmations dengan required_confirmations. Status confirmed saja tidak membuktikan pemeriksaan lainnya sudah lengkap.

Lihat berbagai situasi dalam contoh respons.

Penilaian keseluruhan

overall_state merangkum pemeriksaan transaksi, risiko, sanksi, token, dan rincian pembayaran.

Baca bersama kelengkapan data

Penilaian keseluruhan dan coverage menjelaskan hal berbeda. Temuan berisiko tinggi dapat muncul bersama data yang belum lengkap. Jika fakta transaksi saling bertentangan, LIMITED_DATA mendapat prioritas.

Simpan dan periksa reasons yang benar-benar dikembalikan. Daftar tersebut memuat penjelasan penting dalam jumlah terbatas, bukan seluruh bukti dari setiap sumber.

Kelengkapan dan waktu data

Data lengkap dan tidak lengkap

coverage="complete" berarti data memenuhi kebutuhan pemeriksaan wajib untuk respons tersebut. Ini tidak berarti transaksi aman: hasilnya tetap dapat menunjukkan risiko tinggi.

coverage="partial" berarti sebagian data wajib tidak tersedia, tidak didukung, atau tidak konsisten. Kekurangan dapat berkaitan dengan transaksi, aset, token, maupun penilaian risiko.

• Hasil pemeriksaan sanksi tidak tersedia: sanctions_hit=null, bukan false.
• Risiko belum diketahui: aml_risk_level="unknown".
• Keaslian token belum ditentukan: token_authenticity="unknown". Simbol token tidak membuktikan keasliannya.

LIMITED_DATA dapat dikembalikan dengan HTTP 200. Ini merupakan hasil tentang keterbatasan data, bukan selalu kesalahan koneksi.

Waktu pemeriksaan

Periksa freshness.checked_at, waktu data setiap sumber, dan max_source_age_seconds. Jika waktu sumber bernilai null, waktunya tidak diketahui.

Pengulangan dengan Idempotency-Key yang sama mengembalikan hasil, waktu, dan ID permintaan semula. Pengulangan tidak memperbarui data. Jika memerlukan penilaian yang lebih baru setelah hasil tersebut ditangani, buat operasi pemeriksaan terpisah.

Perhitungan kuota

Hanya pemeriksaan dengan data lengkap yang memakai kuota. Data parsial, kesalahan koneksi, dan pengembalian ulang hasil tersimpan tidak memakai unit tambahan. Aturan yang sama berlaku untuk permintaan dari portal.

Penjelasan hasil

Setiap elemen reasons memiliki code, category, dan severity. Tingkat kepentingannya adalah info, warning, high, dan critical. API mengembalikan 2-5 penjelasan yang diprioritaskan.

Kode baru dapat ditambahkan. Jangan menganggap kode yang belum dikenal sebagai hasil baik. Kode yang tidak muncul juga tidak membuktikan bahwa pemeriksaan terkait telah dilakukan.

Ulangi permintaan tanpa tagihan ganda

Simpan satu kunci untuk setiap pemeriksaan

Idempotency-Key menerima 1 hingga 128 karakter ASCII yang dapat dicetak. Kunci berlaku untuk organisasi Anda dan isi permintaan yang telah dinormalisasi. Gunakan kunci dan isi yang sama saat mencoba kembali, termasuk dari server lain atau setelah mengganti kunci API. Jangan masukkan kredensial atau data pribadi ke dalamnya.

Jika pemeriksaan sudah selesai, API mengembalikan respons yang tersimpan tanpa perubahan, dengan Idempotent-Replayed: true dan X-Request-ID awal. Kunci yang sama dengan isi berbeda menghasilkan 409 idempotency_conflict dan tidak boleh dicoba ulang. Jika pemeriksaan masih berjalan, API mengembalikan 409 idempotency_in_progress beserta Retry-After.

Masa penyimpanan dan respons galat

Masa penyimpanan standar adalah 24 jam. Hubungi dukungan jika kontrak Anda menetapkan masa yang berbeda. Setelah masa ini berakhir, penggunaan kunci yang sama dapat memulai pemeriksaan baru yang dikenai kuota. Batasi percobaan otomatis pada masa penyimpanan dan simpan catatan pembayaran Anda sendiri.

Respons galat yang sudah disimpan, termasuk kegagalan penyedia data atau kuota yang habis, juga dikembalikan tanpa perubahan. retryable=true menjelaskan sifat kegagalannya; nilai ini tidak menghapus respons yang tersimpan.

Hentikan percobaan otomatis jika respons galat disertai Idempotent-Replayed: true. Setelah hasil tersebut dipastikan dan dicatat, Anda dapat memulai pemeriksaan baru jika perlu mendapatkan data terbaru. Jangan membuat kunci baru hanya karena hasil permintaan awal belum diketahui.

Batas permintaan dan kuota

Batas organisasi

Batas mengikuti versi paket yang berlaku atau ketentuan khusus organisasi Anda. Periksa /v1/usage dan halaman Paket dan batas di portal. Nilai dalam contoh tidak merupakan penawaran harga atau jaminan kuota.

Header waktu menggunakan detik Unix. Semua kunci dan pemeriksaan melalui portal memakai kuota organisasi yang sama. Periode bulanan mengikuti UTC, bukan zona waktu browser.

Saat batas tercapai

429 rate_limit_exceeded berarti permintaan terlalu sering. 429 concurrency_limit_exceeded berarti terlalu banyak pemeriksaan sedang berjalan. 429 quota_exceeded berarti kuota habis.

Ikuti Retry-After, termasuk jika waktu tunggu panjang karena kuota bulanan habis. Respons tersimpan tetap melewati pemeriksaan akses serta batas frekuensi dan jumlah permintaan bersamaan, tetapi tidak mengurangi kuota lagi.

Gunakan antrean terbatas di server dan atur jumlah permintaan bersamaan per organisasi. Perubahan paket berlaku untuk hak akses berikutnya dan tidak mengubah riwayat penggunaan.

Percobaan ulang dan batas waktu

Batasi jumlah percobaan

Gunakan batas waktu klien yang lebih panjang dari batas server 12 detik, misalnya 15 detik per percobaan. Target latensi p95 adalah paling lama 5 detik. Target ini menjadi syarat peluncuran, bukan jaminan untuk setiap permintaan. Waktu jaringan berada di luar batas waktu server.

Jika menerima respons galat, coba kembali hanya ketika error.retryable=true. Ikuti Retry-After, tambah jeda secara eksponensial dengan variasi acak, dan batasi jumlah percobaan serta durasi seluruh proses. Jika waktu tunggu melampaui batas proses interaktif, jadwalkan percobaan berikutnya tanpa memperpendek jeda yang diminta server.

Jika jaringan terputus, gunakan kembali isi permintaan dan Idempotency-Key yang telah disimpan. Pertahankan keduanya setelah proses dimulai ulang. Jika galat berasal dari respons tersimpan, hentikan percobaan otomatis dan pastikan hasil operasinya.

409 idempotency_conflict memerlukan perbaikan integrasi. 409 idempotency_in_progress, 429, 503, dan 504 dapat dicoba kembali sesuai aturan di atas.

Catat hanya ID permintaan dan kode galat publik dalam log biasa. Jangan mencatat isi permintaan, kunci API, saldo, atau data mentah penyedia. Contoh integrasi menunjukkan penerapan aturan ini.

Galat dan penanganannya

Format respons galat

{"request_id":"merchant-order-1001-attempt-1","error":{"code":"provider_unavailable","message":"Transaction data is temporarily unavailable","retryable":true}}

X-Request-ID pada header mengidentifikasi respons yang sama. Gunakan code dan retryable untuk menentukan tindakan. Jangan bergantung pada teks message: pesan API pada contoh ditampilkan apa adanya dan dapat berubah.

Kegagalan gateway dapat menghasilkan format yang berbeda. Jika respons tidak ada atau tidak valid, anggap hasil permintaan belum diketahui dan pertahankan kunci idempotensi awal.

Periksa Idempotent-Replayed: mengulang respons galat yang tersimpan tidak memperbarui hasilnya. Lihat idempotensi. Respons HTTP galat tidak selalu berarti permintaan belum diterima.

Keamanan integrasi

Lindungi kredensial

Panggil API dari backend. Simpan kunci dalam pengelola rahasia, batasi akses hanya untuk layanan integrasi, dan ganti kunci jika diduga bocor. Jangan memasukkan kunci ke tiket dukungan, URL, pelacak masalah, analitik, konsol browser, atau kode frontend.

Aktifkan kebijakan autentikasi yang kuat pada penyedia identitas Anda. Terima undangan hanya dari administrator organisasi yang dipercaya. Keluar dari akun setelah menggunakan perangkat bersama. Gunakan pengaturan organisasi untuk mengakhiri semua sesi jika diperlukan.

Tangani data dengan hati-hati

Validasi permintaan pembayaran di server. Hubungkan setiap pemeriksaan dengan ID operasi pembayaran Anda sendiri dan pastikan hasil yang belum jelas sebelum melanjutkan. Gunakan alamat kontrak token yang tepat dan string desimal. Tangani nilai null serta status yang tidak dikenal secara eksplisit.

Tampilkan nama organisasi, label kunci, dan nilai respons sebagai teks yang telah di-escape agar tidak dieksekusi sebagai HTML.

Simpan hanya data yang diperlukan dan batasi akses ke rincian respons. Untuk dukungan, kirim X-Request-ID dan kode galat publik. Jangan kirim kunci, saldo, atau data mentah permintaan dan penyedia.

Referensi API

Unduh OpenAPI. Nama dan tipe kolom diambil langsung dari kontrak API publik. Kolom wajib dapat berisi null jika tipenya mengizinkan. Arti setiap kolom dijelaskan dalam panduan di atas.

POST /v1/transaction/check

Periksa satu transaksi TRON. Kirim JSON dan X-API-Key dari server Anda. Gunakan Idempotency-Key untuk mengulang permintaan tanpa pengurangan kuota ganda.

GET /v1/usage

Lihat batas dan statistik organisasi Anda. Parameter opsional days menerima 1-90 hari, dengan nilai bawaan 30.

ErrorDetail

ErrorResponse

ExposureResponse

FreshnessResponse

ReasonResponse

TransactionCheckRequest

TransactionCheckResponse

TransferResponse

UsageLimitsResponse

UsagePeriodResponse

UsagePlanResponse

UsageRecentResponse

UsageResponse

Riwayat perubahan dan versi

v1.0.0

Pemeriksaan transaksi TRON dan laporan penggunaan organisasi. Portal pengembang menyediakan akses melalui undangan, pengelolaan kunci API, informasi paket, dan halaman uji API untuk organisasi Anda.

Ethereum dan TON masih direncanakan dan belum diterima dalam permintaan API publik. Versi ini tidak mencakup API dompet, webhook, pemantauan, atau pelaksanaan pembayaran.

Perubahan kontrak API

Endpoint publik menggunakan awalan /v1. Dokumentasi versi ini tersedia di /docs/v1/. Berkas OpenAPI dibuat dari model permintaan dan respons yang sama dengan API, lalu dibandingkan dengan versi kontrak yang tersimpan dalam pemeriksaan otomatis.

Integrasi harus menerima kolom respons tambahan sambil tetap memvalidasi kolom yang digunakan. Jangan menganggap kode alasan yang tidak dikenal sebagai hasil aman. Perubahan yang tidak kompatibel memerlukan panduan migrasi berversi; tautan dokumentasi untuk versi utama yang ada tetap dipertahankan.

Status layanan dan dukungan

Status akses

Indikator publik menunjukkan apakah akses API bisnis telah diaktifkan. Indikator ini tidak memeriksa penyedia data secara langsung dan bukan jaminan ketersediaan layanan. Jaringan yang didukung menunjukkan kemampuan produk; akses organisasi Anda dapat lebih terbatas.

503 api_disabled berarti pemeriksaan bisnis belum diaktifkan atau sedang dijeda. 503 provider_unavailable berarti data transaksi yang diperlukan tidak dapat diambil untuk permintaan tersebut. Simpan ID permintaan dan ikuti panduan percobaan ulang.

Hubungi kami

Hubungi tim ChainZap untuk undangan, ketentuan komersial, insiden, dan bantuan integrasi. Sertakan X-Request-ID, kode galat publik, serta waktu UTC. Jangan sertakan kunci API, token identitas, atau data mentah transaksi dan penyedia.

Jaringan: TRON: didukung. Ethereum: direncanakan. TON: direncanakan.