Referensi API

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

Base URL

Environment ditentukan otomatis dari prefix API key:

Prefix Key	Environment	URL
`ipk_sandbox_`	Sandbox (Anvil fork)	`https://sandbox.transx402.com`
`ipk_live_`	Production (Base mainnet)	`https://api.transx402.com`

Autentikasi

Grup Endpoint	Auth	Metode
`/facilitate`	API Key	Header `X-API-Key`
`/payments/*`	API Key	Header `X-API-Key`
`/tokens/*`	Tidak (publik)	—
`/health`	Tidak (publik)	—
`/verify/:txHash`	Tidak (publik)	—
`/auth/*`	Tanda tangan wallet	SIWE
`/merchant/*`	Session cookie	Di-set setelah `/auth/login`
`/sandbox/*`	API Key Sandbox	Header `X-API-Key`

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`

`POST /auth/logout`

Hapus session.

Fasilitasi Pembayaran

`POST /facilitate`

Proses otorisasi pembayaran yang sudah ditandatangani. Ini adalah endpoint inti yang dipanggil oleh client x402.

Auth: API Key (header X-API-Key)

Alur:

Parse dan validasi request
Autentikasi API key, resolve merchant dan environment
Route ke chain yang benar (sandbox Anvil atau production Base)
Verifikasi token ada di registry
Verifikasi tanda tangan Permit2
Cek deadline belum lewat
Cek nonce belum digunakan
Cek saldo IDRX pembayar
Cek allowance Permit2 pembayar
Simulasi transaksi
Kirim transaksi on-chain
Tunggu konfirmasi
Catat pembayaran di database
Kirim webhook (async)
Kembalikan hash transaksi

Status Pembayaran

`GET /payments/:txHash`

Dapatkan status pembayaran berdasarkan hash transaksi.

Auth: API Key

Response:

{
  "txHash": "0x...",
  "status": "confirmed",
  "from": "0xPembayar",
  "to": "0xMerchant",
  "token": "IDRX",
  "amount": "150000000000000000000000",
  "amountFormatted": "150000",
  "currency": "IDR",
  "network": "base",
  "blockNumber": 12345678,
  "timestamp": "2026-04-01T10:30:00Z",
  "resource": "https://example.com/artikel/123"
}

Nilai status: pending, confirmed, failed

`GET /payments`

Daftar pembayaran untuk merchant yang terautentikasi.

Auth: API Key

Parameter query:

Param	Tipe	Deskripsi
`page`	number	Nomor halaman (default: 1)
`limit`	number	Item per halaman (default: 20, max: 100)
`status`	string	Filter berdasarkan status
`from`	string	Filter berdasarkan alamat pembayar
`since`	ISO date	Filter pembayaran setelah tanggal ini
`until`	ISO date	Filter pembayaran sebelum tanggal ini

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": "21345000000000000000000000000",
    "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 di chain sandbox.

Auth: API Key Sandbox

Request:

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

Response:

{
  "txHash": "0x...",
  "address": "0xWalletTest...",
  "amount": "1000000",
  "token": "IDRX",
  "balance": "1000000"
}

`POST /sandbox/reset`

Reset state chain sandbox (re-fork dari block Base mainnet terbaru).

Auth: API Key Sandbox

`GET /sandbox/wallets`

Daftar wallet test yang sudah di-fund dengan saldo IDRX dan ETH.

Auth: API Key Sandbox

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"
}

Verifikasi Pembayaran

`GET /verify/:txHash`

Endpoint publik untuk memverifikasi bahwa pembayaran diproses oleh TransX402. Berguna untuk verifikasi server-side tanpa API key.

Auth: Tidak diperlukan

Response:

{
  "verified": true,
  "txHash": "0x...",
  "token": "IDRX",
  "amount": "150000000000000000000000",
  "from": "0xPembayar",
  "to": "0xMerchant",
  "network": "base"
}

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": "150000000000000000000000",
      "available": "50000000000000000000000"
    }
  }
}

Kode Error

Kode	HTTP Status	Deskripsi
`invalid_signature`	400	Verifikasi tanda tangan Permit2 gagal
`insufficient_balance`	400	Saldo token pembayar kurang
`no_permit2_approval`	400	Pembayar belum approve kontrak Permit2
`expired_deadline`	400	Otorisasi pembayaran sudah kedaluwarsa
`unsupported_token`	400	Token tidak ada di registry
`unsupported_network`	400	Jaringan tidak didukung untuk token ini
`simulation_failed`	400	Simulasi transaksi gagal
`tx_failed`	500	Transaksi on-chain gagal
`rate_limited`	429	Terlalu banyak request
`unauthorized`	401	API key tidak valid atau tidak ada

Rate Limits

Endpoint	Limit
`POST /facilitate`	60/menit per IP
`GET /payments/*`	120/menit per API key
`POST /merchants/*`	10/menit per IP
Lainnya	120/menit per IP

Referensi API

On this page