Library JavaScript

Panduan lengkap @transx402/client — instalasi, konfigurasi, komponen paywall, dan referensi API untuk integrasi pembayaran IDRX.

Ringkasan

@transx402/client adalah library untuk browser dan Node.js yang menangani seluruh alur pembayaran x402 untuk IDRX. Library ini membungkus client x402 standar dan menambahkan logika khusus IDRX: deteksi approval Permit2, prompt approval satu kali, dan konfigurasi default token/network.

Tujuan utama: tanpa kerumitan untuk pemilik website — cukup tambahkan satu script tag atau package npm, dan pembayaran IDRX langsung berfungsi.

Instalasi

NPM (untuk aplikasi yang di-bundle)

npm install @transx402/client

CDN (untuk WordPress, situs statis, halaman HTML biasa)

Untuk integrasi tanpa proses build, lihat panduan khusus Penggunaan CDN. Versi singkatnya:

<script src="https://cdn.transx402.com/v1/transx402.min.js"></script>

Script CDN mengekspos objek global TransX402 dengan API yang sama seperti yang dijelaskan di bawah.

Inisialisasi

`TransX402.create(options)`

Buat instance client TransX402:

// Sandbox (otomatis mengarah ke sandbox.transx402.com)
const client = TransX402.create({
  apiKey: 'ipk_sandbox_abc123...',
});
 
// Production (otomatis mengarah ke api.transx402.com)
const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',
});

Environment (sandbox/production) ditentukan otomatis dari prefix API key — Anda tidak perlu mengatur URL fasilitator secara manual.

Opsi Konfigurasi

Opsi	Tipe	Default	Deskripsi
`apiKey`	`string`	wajib	API key dari dashboard TransX402
`token`	`string`	`'IDRX'`	Simbol token yang digunakan
`network`	`string`	`'base'`	Jaringan blockchain
`onPaymentStart`	`function`	—	Callback saat pembayaran dimulai
`onPaymentSuccess`	`function`	—	Callback saat pembayaran berhasil
`onPaymentError`	`function`	—	Callback saat pembayaran gagal
`onWalletConnect`	`function`	—	Callback saat wallet terhubung
`onApprovalRequired`	`function`	—	Callback saat approval Permit2 diperlukan

API Utama

`client.fetch(url, options)`

Drop-in replacement untuk fetch(). Otomatis menangani respons 402.

const response = await client.fetch('https://example.com/artikel-premium');
const content = await response.json();

Alur internal:

Mengirim request fetch() biasa
Jika respons 402, mem-parse persyaratan pembayaran
Menghubungkan wallet (jika belum)
Memeriksa approval Permit2 (meminta jika belum — satu kali saja)
Menandatangani otorisasi Permit2
Mengirim otorisasi ke fasilitator
Mencoba ulang request asli dengan bukti pembayaran
Mengembalikan respons final

`client.connectWallet()`

Hubungkan wallet secara eksplisit. Mendukung:

MetaMask / wallet ekstensi browser (EIP-1193)
WalletConnect v2
Coinbase Wallet

const address = await client.connectWallet();
console.log('Wallet terhubung:', address);

`client.checkApproval()`

Periksa apakah wallet yang terhubung sudah menyetujui Permit2 untuk IDRX.

const { approved, allowance } = await client.checkApproval();
 
if (!approved) {
  console.log('Perlu approval Permit2');
}

`client.requestApproval()`

Minta approval Permit2 dari pengguna. Hanya diperlukan sekali per wallet.

const tx = await client.requestApproval();
console.log('Approval berhasil, tx hash:', tx);

`client.pay(paymentRequirements)`

Trigger pembayaran secara manual tanpa membungkus fetch.

const result = await client.pay({
  to: '0xWalletMerchant',
  amount: '150000',    // dalam IDR (library mengonversi ke unit IDRX)
  currency: 'IDR',
  resource: 'https://example.com/artikel/123',
});
 
console.log('Pembayaran berhasil:', result.txHash);

Komponen Paywall

Komponen paywall siap pakai untuk content gating.

Vanilla JavaScript

TransX402.paywall({
  selector: '#konten-premium',    // elemen yang di-gate
  price: 5000,                     // harga dalam IDR
  currency: 'IDR',
  merchantWallet: '0xMerchant...',
  title: 'Artikel Premium',
  description: 'Bayar Rp 5.000 untuk membaca artikel ini',
});

React

import { Paywall } from '@transx402/client/react';
 
function ArtikelPage() {
  return (
    <Paywall
      price={5000}
      currency="IDR"
      merchantWallet="0xMerchant..."
    >
      <KontenPremium />
    </Paywall>
  );
}

Tampilan Paywall

Overlay paywall default menampilkan:

Harga dalam IDR (contoh: "Rp 5.000")
Tombol "Pay with IDRX"
Alur koneksi wallet (jika belum terhubung)
Langkah approval Permit2 (jika pertama kali, dengan penjelasan)
Konfirmasi pembayaran dengan link transaksi
Dapat dikustomisasi melalui CSS variables

Kustomisasi

CSS Variables

:root {
  --transx402-primary: #2563eb;
  --transx402-bg: #ffffff;
  --transx402-text: #1a1a1a;
  --transx402-radius: 12px;
  --transx402-font: 'Inter', system-ui, sans-serif;
}

Event Hooks

const client = TransX402.create({
  apiKey: 'ipk_sandbox_abc123...',
  onPaymentStart: (details) => {
    console.log('Pembayaran dimulai:', details);
    // Tracking analytics
  },
  onPaymentSuccess: (result) => {
    console.log('Pembayaran berhasil:', result.txHash);
    // Unlock konten
  },
  onPaymentError: (error) => {
    console.error('Pembayaran gagal:', error.message);
    // Tampilkan pesan error
  },
  onWalletConnect: (address) => {
    console.log('Wallet terhubung:', address);
    // Update UI
  },
  onApprovalRequired: () => {
    console.log('Approval Permit2 diperlukan');
    // Custom approval UI
  },
});

Dukungan Multi-Currency

Library dirancang untuk IDRX terlebih dahulu tetapi mendukung token tambahan:

const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',
  token: 'USDC',       // override token default
  network: 'base',
});

Konfigurasi token (alamat, desimal, metode) diambil dari endpoint /tokens fasilitator, sehingga penambahan token baru tidak memerlukan update library client.

Target Ukuran Bundle

Varian	Target
Core (fetch wrapper saja)	< 15 KB gzipped
Dengan paywall UI	< 30 KB gzipped
Dengan wallet connectors	< 50 KB gzipped
CDN full bundle	< 60 KB gzipped

Kompatibilitas

Browser

Chrome 90+
Firefox 90+
Safari 15+
Edge 90+
Mobile: Chrome Android, Safari iOS

Node.js

Node.js 18+ (membutuhkan Fetch API)
Bisa digunakan server-side untuk pembayaran programatik (AI agent, backend)

Contoh Lengkap

Paywall Artikel Blog

<!DOCTYPE html>
<html>
<head>
  <title>Blog Saya</title>
  <script src="https://cdn.transx402.com/v1/transx402.min.js"></script>
</head>
<body>
  <h1>Panduan Investasi Crypto 2026</h1>
 
  <p>Berikut adalah preview artikel...</p>
 
  <div id="konten-premium">
    <p>Ini adalah konten premium yang akan terbuka setelah pembayaran.</p>
    <!-- Konten lengkap di sini -->
  </div>
 
  <script>
    const client = TransX402.create({
      apiKey: 'ipk_sandbox_abc123...',
    });
 
    TransX402.paywall({
      selector: '#konten-premium',
      price: 5000,
      currency: 'IDR',
      title: 'Konten Premium',
      description: 'Bayar Rp 5.000 untuk membaca artikel lengkap',
    });
  </script>
</body>
</html>

Fetch API dengan Error Handling

import { TransX402 } from '@transx402/client';
 
const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',
  onPaymentError: (error) => {
    if (error.code === 'insufficient_balance') {
      alert('Saldo IDRX Anda tidak mencukupi');
    } else if (error.code === 'user_rejected') {
      console.log('Pengguna membatalkan pembayaran');
    }
  },
});
 
try {
  const response = await client.fetch('https://api.mysite.com/premium-data');
  const data = await response.json();
  renderContent(data);
} catch (error) {
  console.error('Gagal mengambil konten:', error);
}

Library JavaScript

On this page