Server Library

@transx402/server — SDK backend merchant untuk settlement x402 kanonis (respons 402, processGate, proxy config).

Overview

@transx402/server adalah paket Node tanpa runtime dependency untuk backend merchant. Gunakan bersama @transx402/client dalam mode settlement: "server" (default untuk fetch()).

Alur kanonis:

1. Client memanggil API Anda → kembalikan 402 dari payments.processGate / payments.buildRequired
2. Wallet client menandatangani → retry dengan PAYMENT-SIGNATURE
3. Route Handler Anda memanggil tx402.payments.processGate → POST /facilitate dengan X-API-Key di server
4. Jika sukses, kembalikan konten berbayar

TransX402 memakai POST /facilitate gabungan (verify + settle dalam satu panggilan). Simpan key ipk_sandbox_ / ipk_live_ di server.

Untuk paywall / situs statis tanpa endpoint settle merchant, gunakan settlement: "direct" di client.

Membutuhkan Node.js 20.19+. Tidak ada paket middleware Express / Hono / Fastify — teruskan Request / Headers Web Standard (atau header Node http) sendiri. Next.js App Router adalah contoh utama.

Install

npm install @transx402/server
npm install @transx402/client

Sumber: github.com/campinvestment/transx402-server

Anda wajib mengirim environment dan/atau facilitatorUrl ke konstruktor. Keluarga key harus cocok (ipk_sandbox_ ≠ environment: "base").

Quick start (Route Handler)

import { TransX402 } from "@transx402/server";
 
const tx402 = new TransX402(process.env.TRANSX402_API_KEY!, {
  environment: "camp", // atau "local" | "base"
});
 
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 terbuka",
  });
}

priceIdr adalah IDR utuh (dikonversi ×100 ke unit dasar IDRX). payTo harus cocok dengan wallet merchant di dashboard.

Browser / agen:

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

Proxy config (settlement server)

Browser memuat parameter chain via GET /config. Tanpa allowlist CORS domain merchant di fasilitator hosted, panggilan lintas origin gagal. Sediakan proxy same-origin dan arahkan client browser ke sana.

Basis path proxy default: /api/transx402 (client menambahkan /config).

// 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()),
  });
}

Route Handler pembayaran tetap berbicara ke fasilitator langsung untuk body 402 dan POST /facilitate. Hanya browser yang memakai proxy.

API

Client

Hasil processGate:

| { kind: "paymentRequired"; status: 402; body: PaymentRequiredResponse }
| { kind: "settled"; status: 200; txHash: string | null }
| { kind: "failed"; status: 402 | 500; error: string; code?: string; details?: Record<string, string> }

Helper bebas

Utamakan PAYMENT-SIGNATURE; X-PAYMENT adalah cadangan.

Migrasi dari 0.2.x

// Sebelum (dihapus)
const { facilitatorUrl, configSection } = resolveServerConfig({ apiKey, environment });
await processPaymentGate({ headers, facilitatorUrl, apiKey, configSection, ... });
 
// Sesudah
const tx402 = new TransX402(apiKey, { environment });
await tx402.payments.processGate({ headers, payTo, priceIdr, resourceUrl });

Berikut bukan export publik lagi: resolveServerConfig, processPaymentGate, facilitatePayment, verifyPayment, buildPaymentRequired, fetchFacilitatorConfig, handleFacilitatorConfigRequest.

Related

• Library JavaScript — @transx402/client
• Referensi API — GET /config, POST /facilitate, GET /payments/:txHash
• Quickstart — resep Next.js siap salin