@fragmentpay/server

Runtime-agnostic Frag SDK. Zero dependencies. Works in Node 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, and every runtime with global fetch.

All inputs are validated at runtime — bad parameters throw FragValidationError with a clear path (e.g. [frag] createIntent.amount: min 0.01) before a network round-trip.

Install

npm install @fragmentpay/server
# or: bun add @fragmentpay/server
# or: pnpm add @fragmentpay/server

Required environment variables

| Name | Where | Example | | ------------------------ | ----------- | ------------------------------------------ | | FRAG_SECRET_KEY | server only | sk_live_… or sk_test_… | | FRAG_WEBHOOK_SECRET | server only | value shown when you create the webhook | | FRAG_BASE_URL (opt.) | server only | override host, default https://frag.cash |

Never expose sk_… in a browser bundle.

End-to-end example (copy-paste)

1. Create an intent from your backend

// server/frag.ts
import { Frag } from "@fragmentpay/server";

export const frag = new Frag({ secretKey: process.env.FRAG_SECRET_KEY! });

export async function startCheckout(orderId: string, cents: number, email: string) {
  const intent = await frag.paymentIntents.create({
    amount: cents / 100,
    currency: "USD",
    customerEmail: email,
    settlement: {
      chain: "base",
      token: "USDC",
      address: process.env.MERCHANT_USDC_ADDRESS!,
    },
    successUrl: "https://shop.example.com/thanks",
    cancelUrl: "https://shop.example.com/cart",
    metadata: { order_id: orderId },
    idempotencyKey: `order_${orderId}`,
  });
  return { intentId: intent.id, checkoutUrl: intent.checkout_url };
}

2. Verify inbound webhooks

// server/webhook.ts
import { verifyWebhook } from "@fragmentpay/server";

export async function POST(req: Request) {
  const payload = await req.text();
  const event = await verifyWebhook({
    payload,
    signature: req.headers.get("frag-signature"),
    secret: process.env.FRAG_WEBHOOK_SECRET!,
  });

  if (event.type === "payment_intent.settled") {
    await markOrderPaid(event.data as { id: string; metadata: { order_id: string } });
  }
  return new Response("ok");
}

3. React drop-in on the frontend — see @fragmentpay/react.

Advanced options

const frag = new Frag({
  secretKey: process.env.FRAG_SECRET_KEY!,
  baseUrl: "https://frag.cash", // default
  timeoutMs: 15_000, // per-request timeout
  maxRetries: 3, // retries on 5xx / network errors with Retry-After honored
  fetch: myCustomFetch, // inject a custom fetch (Workers, tracing, etc.)
});

Every method throws FragError on non-2xx responses. It carries status, code, message, and requestId for observability, plus the raw provider body when available.

Validation errors

Every method validates its arguments and throws a FragValidationError before touching the network:

frag.paymentIntents.create({ amount: -5 });
// FragValidationError: [frag] createIntent.amount: min 0.01

Public API surface

• frag.paymentIntents.{create, retrieve, list, cancel, transactions, routing}
  • routing(id) returns router candidates evaluated for the intent (chosen + rejected with reasons). route(id) is kept as a deprecated alias.
• frag.refunds.{create, retrieve, list, retry, status} — retry(id, { destination }) requeues a failed refund, optionally to a different address
• frag.payouts.{retrieve, list, replay}
• frag.webhookEndpoints.{create, list, retrieve, update, delete, rotateSecret}
• frag.tokens.list({ chain })
• verifyWebhook({ payload, signature, secret })
• FragError (HTTP + upstream) and FragValidationError (input)

Idempotency

Every POST accepts an optional Idempotency-Key header (SDK auto-sends it when you set idempotencyKey). Replays within 24h with the same body return the original response; a different body returns HTTP 409 with code: "idempotency_conflict".

Webhook events

The SDK's WebhookEventType union stays in sync with the API. Notable events: payment_intent.created, payment_intent.quoted, payment_intent.executing, payment_intent.settled, payment_intent.failed, payment_intent.expired, payment_intent.cancelled, payment_intent.refunded, payout.created, payout.paid, payout.failed, ping.

License

MIT