Quickstart

Step-by-step guide to start accepting IDRX payments — register, pick a stack (Next.js, WordPress, or CDN), and take your first sandbox payment live.

This guide takes you from zero to your first IDRX payment, then to production. Pick one stack and copy the recipe. Deep-dive APIs live on the integration pages.

Onboarding at a Glance

Prerequisites

• A TransX402 merchant account (next step)
• MetaMask (or another EIP-1193 injected wallet) for browser payments
• One of: a Next.js App Router app (Node.js 20.19+), a WordPress 6.2+ site, or a static HTML page

Secret keys (ipk_sandbox_, ipk_live_) stay on the server. Publishable keys (ipk_pub_sandbox_, ipk_pub_live_) are for CDN / direct settlement only.

Step 1: Register on the Dashboard

Go to dashboard.transx402.com and connect your wallet.

1. Click "Connect Wallet" and select MetaMask (or another EIP-1193 wallet)
2. Sign the verification message (SIWE — Sign-In with Ethereum)
3. Fill in your merchant profile: business name, email, and website URL

After registration, you automatically receive a sandbox secret API key.

Step 2: Get Your Keys and Merchant Wallet

On the API Keys page you will see the sandbox secret key created at signup:

ipk_sandbox_abc123def456...

Important: The full secret key is only displayed once. Copy it into server env / WordPress settings — never into frontend JavaScript for Next.js.

Also copy your merchant wallet from the dashboard. Every recipe needs it as payTo (server) or merchantWallet (CDN). A missing wallet fails the first payment.

CDN only: create a publishable sandbox key (ipk_pub_sandbox_...) and register this page's origin under Allowed Origins. Direct settlement rejects secret keys when the browser sends an Origin header.

Step 3: Pick a Stack

A. Next.js (canonical)

Merchant backend settles. The browser signs; it never holds an API key and never calls POST /facilitate.

npm install @transx402/server @transx402/client

Env (server only):

TRANSX402_API_KEY=ipk_sandbox_...
MERCHANT_WALLET=0xYourMerchantWallet

Paid route (app/api/premium/route.ts):

import { TransX402 } from "@transx402/server";
 
const tx402 = new TransX402(process.env.TRANSX402_API_KEY!, {
  environment: "camp",
});
 
export async function GET(request: Request) {
  const gate = await tx402.payments.processGate({
    headers: request.headers,
    payTo: process.env.MERCHANT_WALLET!,
    priceIdr: "5000",
    resourceUrl: request.url,
  });
 
  if (gate.kind === "paymentRequired") {
    return Response.json(gate.body, { status: 402 });
  }
  if (gate.kind === "failed") {
    return Response.json(
      { error: gate.error, code: gate.code, details: gate.details },
      { status: gate.status }
    );
  }
 
  return Response.json({
    paid: true,
    txHash: gate.txHash,
    content: "Premium unlocked",
  });
}

Same-origin config proxy so the browser can load chain params without facilitator CORS (app/api/transx402/config/route.ts):

import { TransX402 } from "@transx402/server";
 
const tx402 = new TransX402(process.env.TRANSX402_API_KEY!, {
  environment: "camp",
});
 
export async function GET(request: Request) {
  return tx402.config.handleRequest(request, {
    isConfigured: () => Boolean(process.env.TRANSX402_API_KEY?.trim()),
  });
}

Browser (no API key):

import { createBrowserClient } from "@transx402/client/browser";
 
const client = createBrowserClient({
  environment: "camp",
  settlement: "server",
  configProxyPath: "/api/transx402",
});
 
const response = await client.fetch("/api/premium");

See the Server Library and JavaScript Library for the full APIs.

B. WordPress Paywall

No application code. The plugin settles in PHP with your secret key.

1. In WordPress admin: Plugins → Add New → search TransX402 Paywall → Install and activate (wordpress.org)
2. Settings → TransX402 — paste the sandbox secret key and merchant wallet (both required before the first payment)
3. Edit a post → document sidebar panel TransX402 Paywall → enable, set price in IDR, publish
4. Open the post logged out, or as an editor with ?transx402_as_visitor=1

Fallback: upload a ZIP whose folder is transx402-paywall/ from GitHub releases.

This is not a shortcode or a Gutenberg block. See the WordPress Plugin guide.

C. CDN paywall (direct settlement)

Zero backend. The browser calls POST /facilitate with a publishable key.

<div id="premium-content">
  <p>This premium content unlocks after payment.</p>
</div>
 
<script type="module">
  import TransX402 from "https://cdn.transx402.com/v1/transx402.browser.min.js";
 
  TransX402.paywall({
    apiKey: "ipk_pub_sandbox_...",
    environment: "camp",
    selector: "#premium-content",
    price: 5000,
    currency: "IDR",
    merchantWallet: "0xYourMerchantWallet",
    title: "Premium Article",
    description: "Pay Rp 5,000 to read this article",
  });
</script>

Register this origin in the dashboard before testing. Prices are whole IDR (5000 = Rp 5,000). See CDN Usage.

Step 4: Test in Sandbox

Fund a test wallet

Use the Sandbox page in the dashboard (Fund IDRX, and Fund ETH for the first MetaMask Permit2 approve). Or call the faucet with your secret sandbox key:

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

Make a test payment

1. Open the paywalled page or call client.fetch("/api/premium")
2. Click "Pay with IDRX" (or confirm the wallet prompt from fetch)
3. Connect MetaMask on CAMP Testnet
4. Approve Permit2 (first time only — this needs test ETH)
5. Sign the payment
6. Content unlocks

Check the dashboard

On Payments: transaction hash, payer, IDRX amount, confirmation, time.

More detail: Sandbox.

Step 5: Go Live

The facilitator host stays https://api.transx402.com. No other protocol changes.

Next Steps

• JavaScript Library — createBrowserClient, paywall, agents
• Server Library — @transx402/server 0.3 (processGate, config proxy)
• CDN Usage — ESM bundle, publishable keys
• WordPress Plugin — TransX402 Paywall 1.0
• API Reference — GET /config, POST /facilitate
• Sandbox — faucet, CAMP vs Anvil
• Webhooks — payment notifications
• Cashing Out — IDRX to bank Rupiah