Referensi API

Dokumentasi lengkap semua endpoint REST API TransX402 — autentikasi, manajemen merchant, fasilitasi pembayaran, sandbox, dan lainnya.

Base URL

Semua request hosted mengarah ke https://api.transx402.com. Pengembangan lokal memakai http://localhost:3402.

Chain ditentukan dari prefix API key Anda (rahasia atau publishable):

IDRX memakai 2 desimal. String amount on-chain dan catatan pembayaran adalah unit dasar (Rp 5.000 → "500000"). Harga manusiawi di SDK adalah IDR utuh ("5000").

Autentikasi

Rahasia vs publishable: POST /facilitate dari browser (Origin ada) harus memakai ipk_pub_* dan Allowed Origin dari dashboard. Key rahasia (ipk_sandbox_, ipk_live_) untuk backend merchant (@transx402/server, PHP WordPress) tanpa Origin browser.

Autentikasi dan Registrasi

POST /auth/register

Daftarkan akun merchant baru. Memerlukan tanda tangan SIWE untuk membuktikan kepemilikan wallet.

Request:

{
  "email": "merchant@example.com",
  "walletAddress": "0xMerchant...",
  "name": "Blog Saya",
  "website": "https://blogsaya.com",
  "signature": "0x...",
  "message": "Sign in to TransX402\nNonce: abc123\nTimestamp: 2026-04-01T10:00:00Z"
}

Response:

{
  "merchantId": "m_abc123",
  "email": "merchant@example.com",
  "walletAddress": "0xMerchant...",
  "sandboxApiKey": "ipk_sandbox_...",
  "createdAt": "2026-04-01T10:00:00Z"
}

Saat registrasi, sandbox API key otomatis dibuat. Production key dibuat terpisah dari dashboard.

POST /auth/login

Login dengan tanda tangan wallet. Menyimpan session cookie untuk akses dashboard.

POST /auth/logout

Hapus session.

Config fasilitator

GET /config

Snapshot publik chain, token, dan kapabilitas x402. Tanpa API key. Client dan @transx402/server memuat RPC, chainId, alamat IDRX, desimal, dan Permit2 dari sini — jangan hardcode di kode aplikasi.

Browser dalam settlement server harus memanggil ini via proxy same-origin merchant (GET /api/transx402/config), bukan origin fasilitator (CORS).

Response (bentuk):

{
  "sandbox": {
    "rpcUrl": "https://testnet-rpc.onchainfolio.com/rpc",
    "chainId": 1337,
    "network": "sandbox",
    "tokens": { "IDRX": "0x..." },
    "tokenDecimals": { "IDRX": 2 },
    "permit2Address": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "x402": {
      "caip2Network": "eip155:1337",
      "sponsorshipMode": "erc20ApprovalRelay",
      "eip2612": false,
      "x402Permit2ProxyAddress": "0x..."
    },
    "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 }
  },
  "production": {
    "rpcUrl": "https://mainnet.base.org",
    "chainId": 8453,
    "network": "base",
    "tokens": { "IDRX": "0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22" },
    "tokenDecimals": { "IDRX": 2 },
    "permit2Address": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "x402": {
      "caip2Network": "eip155:8453",
      "sponsorshipMode": "erc20ApprovalRelay",
      "eip2612": false,
      "x402Permit2ProxyAddress": "0x..."
    },
    "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 }
  }
}

ipk_sandbox_ / ipk_pub_sandbox_ memakai section sandbox; ipk_live_ / ipk_pub_live_ memakai production. rpcUrl / chainId / alamat yang tepat berasal dari fasilitator live.

Fasilitasi Pembayaran

POST /facilitate

Proses otorisasi pembayaran yang sudah ditandatangani. Ini adalah endpoint inti yang dipanggil oleh client x402 (@transx402/server dalam mode kanonis, atau client browser pada settlement: "direct").

Auth: API Key (header X-API-Key). Pemanggil browser harus memakai key publishable plus Allowed Origins.

Alur:

1. Parse dan validasi request
2. Autentikasi API key, resolve merchant dan environment
3. Route ke chain yang benar (sandbox CAMP Testnet atau production Base)
4. Verifikasi token ada di registry
5. Verifikasi tanda tangan Permit2
6. Cek deadline belum lewat
7. Cek nonce belum digunakan
8. Cek saldo IDRX pembayar
9. Cek allowance Permit2 pembayar
10. Simulasi transaksi
11. Kirim transaksi on-chain
12. Tunggu konfirmasi
13. Catat pembayaran di database
14. Kirim webhook (async)
15. Kembalikan hash transaksi

Status Pembayaran

GET /payments/:txHash

Lookup pasca-settlement: cek apakah TransX402 sudah merekam pembayaran untuk hash transaksi ini. Dibatasi ke merchant dari API key. Gunakan untuk unlock tertunda (mis. WordPress pay-per-article) atau rekonsiliasi setelah Anda punya txHash.

Ini bukan langkah verify pre-settlement protokol x402. Settlement memakai POST /facilitate gabungan (verify + settle internal).

Auth: API Key

Response:

{
  "verified": true,
  "txHash": "0x...",
  "status": "confirmed",
  "from": "0xPembayar",
  "to": "0xMerchant",
  "token": "IDRX",
  "amount": "500000",
  "network": "base",
  "blockNumber": 12345678,
  "timestamp": "2026-04-01T10:30:00Z",
  "resource": "https://example.com/artikel/123",
  "description": null
}

Nilai status: pending, confirmed, failed

verified bernilai true jika status === "confirmed". resource adalah URL konten dari pembayaran asli (gunakan untuk mencocokkan unlock pay-per-article). resource dan description bisa null jika tidak disediakan saat settlement.

Alias deprecated: GET /verify/:txHash mengembalikan response yang sama dengan header Deprecation: true. Gunakan /payments/:txHash.

GET /payments

Daftar pembayaran untuk merchant yang terautentikasi.

Auth: API Key

Parameter query:

Response:

{
  "payments": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Profil Merchant

GET /merchant/me

Dapatkan profil merchant saat ini.

Auth: Session cookie

PATCH /merchant/me

Update profil merchant.

Auth: Session cookie

Request:

{
  "name": "Blog Saya (Updated)",
  "webhookUrl": "https://blogsaya.com/webhook/transx402",
  "webhookSecret": "auto",
  "defaultToken": "IDRX",
  "defaultNetwork": "base"
}

GET /merchant/stats

Dapatkan statistik pembayaran.

Auth: Session cookie

Response:

{
  "totalPayments": 1423,
  "totalVolume": {
    "IDRX": "2134500000000",
    "formatted": {
      "IDRX": "21,345,000,000 IDR"
    }
  },
  "last30Days": {
    "payments": 342,
    "volume": { "IDRX": "..." },
    "uniquePayers": 89
  }
}

Manajemen API Key

POST /merchant/api-keys

Buat API key baru.

Auth: Session cookie

Request:

{
  "environment": "sandbox",
  "label": "WordPress Site"
}

Response:

{
  "id": "key_abc123",
  "key": "ipk_sandbox_abc123def456...",
  "prefix": "ipk_sandbox_abc1",
  "environment": "sandbox",
  "label": "WordPress Site",
  "createdAt": "2026-04-01T10:00:00Z"
}

Penting: Field key lengkap hanya dikembalikan sekali saat pembuatan. Simpan dengan aman.

GET /merchant/api-keys

Daftar semua API key (menampilkan prefix, label, environment, terakhir digunakan — tidak pernah key lengkap).

Auth: Session cookie

DELETE /merchant/api-keys/:id

Cabut (revoke) API key.

Auth: Session cookie

Utilitas Sandbox

Endpoint ini hanya bisa diakses menggunakan API key sandbox.

POST /sandbox/fund

Isi wallet test dengan IDRX atau ETH di chain sandbox. token opsional default "IDRX". Untuk IDRX, amount adalah IDRX utuh (sama dengan IDR utuh), batas default 100000 per request. Gunakan "ETH" dengan amount desimal seperti "0.01".

Auth: API key sandbox rahasia (ipk_sandbox_... saja)

Request (IDRX):

{
  "address": "0xWalletTest...",
  "amount": "10000"
}

Request (ETH):

{
  "address": "0xWalletTest...",
  "amount": "0.01",
  "token": "ETH"
}

Response:

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

POST /sandbox/reset

Re-fork sandbox Anvil dari block Base mainnet terbaru. Mengembalikan 409 sandbox_operation_unsupported pada sandbox CAMP hosted (treasury).

Auth: API key sandbox rahasia

GET /sandbox/wallets

Daftar wallet test deterministik Anvil. Mengembalikan 409 pada sandbox CAMP hosted (treasury).

Response:

{
  "wallets": [
    {
      "address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
      "ethBalance": "10000.0",
      "idrxBalance": "10000000000",
      "privateKey": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
    }
  ]
}

Ini adalah akun deterministik Anvil — aman untuk diekspos di sandbox saja.

Informasi Token

GET /tokens

Daftar semua token yang didukung.

Auth: Tidak diperlukan

GET /tokens/:symbol/price

Dapatkan informasi harga token.

Auth: Tidak diperlukan

Response:

{
  "symbol": "IDRX",
  "currency": "IDR",
  "rate": 1.0,
  "lastUpdated": "2026-04-01T10:30:00Z"
}

Health Check

GET /health

Auth: Tidak diperlukan

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "networks": {
    "base": { "status": "ok", "blockNumber": 12345678 }
  }
}

Format Error

Semua error mengikuti format yang konsisten:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Payer IDRX balance is below required amount",
    "details": {
      "required": "500000",
      "available": "100000"
    }
  }
}

Kode Error

Rate Limits