Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.unseen.finance/llms.txt

Use this file to discover all available pages before exploring further.

You have the why from the Introduction; this page is the shortest happy path. Payments are created on your server with @unseen_fi/sdk and handed to the modal via createPaymentSession. When it works once, continue to Architecture so every hop has a label.

​
Prerequisites

  • Merchant API key (usk_test_* or usk_live_*)
  • Node 18+ for server code; React 18+ for UI

​
1. Install packages

npm install @unseen_fi/sdk @unseen_fi/ui

​
2. Create a payment on the server

Use UnseenClient with your secret key. Default API hosts follow the network you pass (see Environments).
server.ts
import { UnseenClient } from "@unseen_fi/sdk";

const unseen = new UnseenClient({
  apiKey: process.env.UNSEEN_API_KEY!,
  network: "mainnet", // or "devnet"
});

export async function createCheckoutSession(input: {
  amount: number;
  reference: string;
  description?: string;
}) {
  return unseen.payments.create({
    amount: input.amount,
    reference: input.reference,
    description: input.description,
  });
}
Expose the result to your front end as JSON (include id, checkoutUrl, reference, amount, and paymentToken if your API returns one).

​
3. Wire the React checkout

Wrap your app with UnseenProvider and pass a createPaymentSession that calls your endpoint (not Unseen directly from the browser with a live secret).
app.tsx
"use client";

import {
  UnseenProvider,
  UnseenPayButton,
} from "@unseen_fi/ui";

export function Checkout() {
  return (
    <UnseenProvider baseUrl="https://unseen.finance">
      <UnseenPayButton
        amount={50_000_000}
        reference="order_123"
        description="Premium plan"
        createPaymentSession={async (input) => {
          const res = await fetch("/api/unseen/create-payment", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(input),
          });
          if (!res.ok) throw new Error("Failed to create session");
          return res.json();
        }}
        onSuccess={(p) => console.log("Confirmed", p.txSignature)}
      />
    </UnseenProvider>
  );
}
<UnseenProvider> defaults baseUrl to https://unseen.finance if omitted. It must match the deployment your front end should call for /api/... routes.

​
4. Confirm fulfillment

  • Client: the built-in modal polls verify after the user taps I have paid (hooks).
  • Server: call unseen.payments.verify(paymentId) or handle signed webhooks.
The flow above is intentionally minimal. Next, read Architecture so you can map each step to Browser / backend / gateway / Solana. After fundamentals, deepen the server SDK (Installation) and only then customise webhooks (Webhooks overview) and frameworks (Guides).