Integration Guide

NAVEN_API_URL=https://api.naven.network
NAVEN_API_KEY=naven_api_...
NAVEN_MERCHANT_ID=...

type PaymentIntent = {
  id: string;
  merchantId: string;
  externalId: string;
  customerRef: string | null;
  status: "pending" | "settling" | "settled" | "failed" | "expired";
  amountUsdCents: number;
  currency: "USD";
  paymentUrl: string;
  transactionHash: string | null;
  failureCode: string | null;
  failureMessage: string | null;
  expiresAt: string;
  settledAt: string | null;
};

const navenApiUrl = process.env.NAVEN_API_URL!;
const navenApiKey = process.env.NAVEN_API_KEY!;
const merchantId = process.env.NAVEN_MERCHANT_ID!;

async function navenRequest<T>(path: string, init?: RequestInit): Promise<T> {
  const response = await fetch(`${navenApiUrl}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${navenApiKey}`,
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });

  const body = await response.json();

  if (!response.ok) {
    throw new Error(`${body.code ?? response.status}: ${body.message ?? "Naven request failed"}`);
  }

  return body as T;
}

export function createNavenPaymentIntent(input: {
  orderId: string;
  customerId: string;
  amountUsdCents: number;
}) {
  return navenRequest<PaymentIntent>("/v1/payment-intents", {
    method: "POST",
    body: JSON.stringify({
      merchantId,
      amountUsdCents: input.amountUsdCents,
      externalId: input.orderId,
      customerRef: input.customerId,
      description: "Workspace credit top-up",
    }),
  });
}

export function getNavenPaymentIntent(intentId: string) {
  return navenRequest<PaymentIntent>(
    `/v1/payment-intents/${encodeURIComponent(intentId)}`,
  );
}

POST /api/topups
Authorization: your application session

const topup = await fetch("/api/topups", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ amountUsdCents: 9900 }),
}).then(response => response.json());

// x402Fetch performs the initial request, signs the 402 requirement with the
// connected wallet, and retries with PAYMENT-SIGNATURE.
const paymentResponse = await x402Fetch(topup.paymentUrl, {
  method: "POST",
});

if (!paymentResponse.ok) {
  throw new Error("Payment did not settle");
}

// Treat this as immediate UX feedback only. Ask your backend to confirm and
// fulfill the order from Naven's authenticated status endpoint.
await fetch(`/api/topups/${topup.orderId}/confirm`, { method: "POST" });