Sandbox

Panduan lengkap testing di environment sandbox TransX402 — fund wallet, lakukan pembayaran test, dan validasi integrasi Anda.

Apa itu Sandbox?

Sandbox adalah environment testing untuk menguji integrasi TransX402 tanpa uang sungguhan. Secara default sandbox mengarah ke CAMP Testnet — chain testnet publik (https://testnet-rpc.onchainfolio.com/rpc) dengan IDRX test dan Permit2. Facilitator mensponsori gas settle; merchant mengisi wallet dengan IDRX dan ETH test lewat faucet treasury (/sandbox/fund).

Opsional: Anvil lokal dengan SANDBOX_FUNDING_MODE=anvil dan docker compose --profile anvil up (bukan default).

Paket npm membutuhkan Node.js 20.19+ (^20.19.0 || ^22.13.0 || >=24). Path 4 di browser membutuhkan MetaMask (atau wallet EIP-1193 lain) plus ETH test untuk approve Permit2 pertama.

Sandbox vs Production

Cara Memulai

1. Dapatkan API Key Sandbox

Saat Anda mendaftar di dashboard.transx402.com, API key sandbox rahasia otomatis dibuat. Anda juga bisa membuat key sandbox tambahan (rahasia atau publishable) di halaman API Keys:

ipk_sandbox_abc123def456...

Simpan key rahasia di server / WordPress. Paywall CDN membutuhkan key publishable ipk_pub_sandbox_... dan Allowed Origins.

2. Fund Wallet Test

Sebelum melakukan pembayaran test, isi wallet dengan IDRX test (dan ETH untuk gas Path 4 di browser). Ada dua cara:

Via Dashboard

Buka halaman Sandbox di dashboard. Gunakan kartu Fund IDRX dan Fund ETH (dana dikirim ke wallet merchant terdaftar), lalu klik tombol fund pada masing-masing kartu.

Di CAMP Testnet (treasury), faucet dapat mentransfer IDRX test dan ETH native. Pembayaran browser pertama mungkin meminta Spending Cap MetaMask (approve Permit2); pembayaran berikutnya cukup tanda tangan.

Via API

IDRX:

curl -X POST https://api.transx402.com/sandbox/fund \
  -H "X-API-Key: ipk_sandbox_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xAlamatWalletAnda...",
    "amount": "10000"
  }'

ETH (token opsional — kosongkan untuk IDRX):

curl -X POST https://api.transx402.com/sandbox/fund \
  -H "X-API-Key: ipk_sandbox_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xAlamatWalletAnda...",
    "amount": "0.01",
    "token": "ETH"
  }'

Response:

{
  "txHash": "0x...",
  "address": "0xAlamatWalletAnda...",
  "amount": "0.01",
  "token": "ETH",
  "balance": "10000000000000000"
}

Pakai key sandbox rahasia pada /sandbox/fund. Fund wallet pembayar (akun MetaMask yang akan membayar), bukan hanya wallet merchant.

Testing Pembayaran

Alur Testing Dasar

1. Pasang integrasi — ikuti resep Quickstart untuk Next.js, WordPress, atau CDN
2. Fund wallet — isi wallet pembayar dengan IDRX (dan ETH) via halaman Sandbox di dashboard atau /sandbox/fund
3. Akses konten — buka halaman berpaywall atau panggil client.fetch("/api/premium")
4. Bayar — klik "Pay with IDRX", hubungkan MetaMask di CAMP Testnet, dan tanda tangani
5. Verifikasi — cek pembayaran di dashboard atau via API /payments

Testing dengan Library JS (settlement server)

import { createBrowserClient } from "@transx402/client/browser";
 
// Tanpa API key di browser. Backend merchant settle via @transx402/server.
const client = createBrowserClient({
  environment: "camp", // "local" | "camp" | "base"
  settlement: "server",
  configProxyPath: "/api/transx402", // GET /api/transx402/config
});
 
const response = await client.fetch("/api/premium");

Anda juga bisa set facilitatorUrl untuk menimpa host preset; section config tetap mengikuti environment. Konstruktor server membutuhkan environment dan/atau facilitatorUrl. Parameter chain hanya dari GET /config (atau proxy config Anda).

Browser wallet memakai Path 4: approve Permit2 sekali (user bayar gas), lalu pembayaran hanya signature. Agent memakai Path 3 (createAgentClient) dengan sponsored approve via signTransaction — MetaMask tidak bisa Path 3.

Paywall CDN memakai browser bundle: TransX402.paywall({ apiKey: "ipk_pub_sandbox_...", environment: "camp", ... }). WordPress tidak memakai CDN; plugin menyertakan client dan settle di PHP.

Testing dengan cURL

# 1. Cek health
curl https://api.transx402.com/health
 
# 2. Config chain / token publik (tanpa API key)
curl https://api.transx402.com/config
 
# 3. Fund wallet test
curl -X POST https://api.transx402.com/sandbox/fund \
  -H "X-API-Key: ipk_sandbox_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"address": "0xWalletTest", "amount": "10000"}'
 
# 4. Cek pembayaran
curl https://api.transx402.com/payments \
  -H "X-API-Key: ipk_sandbox_abc123..."

amount pada /sandbox/fund untuk IDRX adalah IDRX utuh (sama dengan IDR utuh). Batas default 100000 per request — jangan kirim "1000000". Catatan pembayaran dari GET /payments memakai unit dasar 2 desimal (Rp 5.000 → "500000").

Perbedaan dengan Production

Kode integrasi sama untuk sandbox dan production. Ganti keluarga key dan environment:

// Sandbox / CAMP — settlement server (browser)
const sandbox = createBrowserClient({
  environment: "camp",
  settlement: "server",
  configProxyPath: "/api/transx402",
});
 
// Production / Base — sama, dengan env server TRANSX402_API_KEY=ipk_live_...
const live = createBrowserClient({
  environment: "base",
  settlement: "server",
  configProxyPath: "/api/transx402",
});

Paywall CDN: ipk_pub_sandbox_ + environment: "camp" → ipk_pub_live_ + environment: "base".

Development Lokal dengan Anvil (opsional)

Anvil bukan sandbox default. Pakai hanya jika butuh fork Base offline:

# Di .env:
# SANDBOX_FUNDING_MODE=anvil
# SANDBOX_RPC_URL=http://host.docker.internal:8546
 
docker compose --profile anvil up -d

Anvil di port 8546. /sandbox/wallets dan /sandbox/reset hanya untuk mode Anvil.

Wallet test Anvil bawaan

curl http://localhost:3402/sandbox/wallets \
  -H "X-API-Key: ipk_sandbox_abc123..."

Ini akun deterministik Anvil. Private key hanya berlaku di chain Anvil.

Reset Anvil

curl -X POST http://localhost:3402/sandbox/reset \
  -H "X-API-Key: ipk_sandbox_abc123..."

Ini re-fork Anvil dari block Base mainnet terbaru. Semua transaksi sandbox Anvil sebelumnya hilang; kontrak IDRX dan Permit2 tetap tersedia. Jangan memanggil reset ke CAMP Testnet hosted dengan harapan chain di-fork ulang.

Mengapa Anvil Fork (opsional)?

Tips Testing

1. Selalu test di sandbox dulu sebelum beralih ke production
2. Gunakan webhook untuk memverifikasi notifikasi pembayaran
3. Test skenario error — saldo kurang, approval Permit2 belum ada
4. Cek dashboard — pembayaran harus muncul di halaman Payments
5. Wallet — MetaMask (EIP-1193). Client tidak menyertakan SDK WalletConnect atau Coinbase Wallet