Server Library

@transx402/server — merchant backend helpers for canonical x402 settlement (402 responses, facilitatePayment, processPaymentGate).

Overview

@transx402/server is a zero-dependency Node package for merchant backends. Use it with @transx402/client in settlement: "server" mode (the default for fetch()).

Canonical flow:

Client hits your API → return 402 + buildPaymentRequired(...)
Client wallet signs → retries with PAYMENT-SIGNATURE
Your Route Handler calls facilitatePayment / processPaymentGate → POST /facilitate with server X-API-Key
On success, return paid content

TransX402 uses a combined POST /facilitate (verify + settle in one call). Keep ipk_ API keys on the server for this mode.

For paywall / static sites without a merchant settle endpoint, use client settlement: "direct" instead.

Install

npm install @transx402/server
# Peer workflow:
npm install @transx402/client

Source: github.com/campinvestment/transx402-server

Quick start (Route Handler)

import {
  processPaymentGate,
  resolveServerConfig,
} from "@transx402/server";
 
const apiKey = process.env.TRANSX402_API_KEY!;
const { facilitatorUrl, configSection } = resolveServerConfig({
  apiKey,
  environment: "local", // or "camp" | "base"
});
 
export async function GET(request: Request) {
  const gate = await processPaymentGate({
    headers: request.headers,
    facilitatorUrl,
    apiKey,
    configSection,
    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 }, { status: gate.status });
  }
 
  return Response.json({
    paid: true,
    txHash: gate.txHash,
    content: "Premium unlocked",
  });
}

Browser / agent:

import { createBrowserClient } from "@transx402/client/browser";
 
const client = createBrowserClient({
  apiKey: "ipk_sandbox_...",
  environment: "local",
  settlement: "server", // default for fetch()
});
 
await client.fetch("/api/premium");

API

Export	Purpose
`buildPaymentRequired`	Build x402 v2 402 JSON from facilitator `/config`
`facilitatePayment`	Decode header → `POST /facilitate`
`processPaymentGate`	No header → 402; header → facilitate
`hasPaymentHeader` / `getPaymentHeader`	Read `PAYMENT-SIGNATURE` / `X-PAYMENT`
`decodePaymentSignature`	Base64 JSON decode of payment payload
`verifyPayment`	Post-settlement `GET /payments/:txHash` (requires API key)
`toIdrxBaseUnits`	Whole IDR → IDRX base units (×100)
`resolveServerConfig` / `FACILITATOR_PRESETS`	Facilitator URL + sandbox/production section

JavaScript Library — @transx402/client
API Reference — POST /facilitate, GET /payments/:txHash

Server Library

Overview

Install

Quick start (Route Handler)

API

Related

On this page