Server SDK (@ionicfi/sdk)

​

Install

npm install @ionicfi/sdk@^0.4.1

​

Quickstart

import { Ionic } from "@ionicfi/sdk";

const secretKey = process.env.IONIC_SECRET_KEY;
if (!secretKey) {
  throw new Error("IONIC_SECRET_KEY is required and was not set");
}
const ionic = new Ionic({ token: secretKey });

const session = await ionic.checkout.sessions.create({
  mode: "payment",
  line_items: [{ price_id: "price_Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8", quantity: 1 }],
  success_url: "https://example.com/return?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "https://example.com/",
});

console.log(session.url); // redirect the buyer here

​

Connect requests

const setup = await ionic.setupIntents.create(
  { currency: "usd", customer: "cus_...", "Idempotency-Key": "save-request:123" },
  { account: "mer_..." },
);

​

Webhooks

import { webhooks } from "@ionicfi/sdk";

const event = webhooks.unwrap(rawBody, requestHeaders, process.env.IONIC_WEBHOOK_SECRET);

​

Typed imports

import type { PaymentIntent, CheckoutSession } from "@ionicfi/sdk";

​

Error handling

​

Reliability

• Idempotency keys are automatic. Every mutating request (POST, PUT, PATCH, DELETE) carries an Idempotency-Key; the SDK generates one per call when you don’t supply your own, so the automatic retries below replay the original operation instead of repeating it (a second charge, a second refund). To also make your own application-level retries safe, pass the same "Idempotency-Key" field with the same request body: the original response is replayed instead of the operation running twice.
• Retries. Requests that fail with 408, 429, 502, 503, or 504 are retried automatically with backoff. A bare 500 is never retried: on a mutating endpoint it can mean the operation already committed. A 502 carrying GATEWAY_ERROR is not retried either: on confirmation and refunds no money moved and the same key would only replay it; on capture and cancel, retrieve the payment intent before retrying.
• Auto-pagination. List calls on paymentIntents, charges, refunds, customers, invoices, subscriptions, creditNotes, paymentMethods, setupIntents, catalog.products, catalog.prices, paymentLinks, checkout.sessions, and webhookEndpoints return a Page that exposes hasNextPage() / getNextPage() and is directly for await-able. Iteration advances with starting_after cursors. The result is not a snapshot of concurrent writes:
  const page = await ionic.paymentIntents.list({ limit: 100 });
  for await (const intent of page) {
    console.log(intent.id);
  }
  
  If the first request carried an offset, continuation requests drop it; iteration advances by cursor alone. Webhook-endpoint lists preserve their legacy full-result behavior when limit is omitted; the returned Page is terminal in that case.

​

Security

• The secret key (sk_v1_test_… / sk_v1_live_…) authenticates every request in this SDK. Keep it server-side only, read from an environment variable. Never ship it to a browser or commit it to source control.
• The webhook signing secret (whsec_…) is returned once, at endpoint creation. If you lose it, call webhookEndpoints.rotateSecret() for a new one; the previous secret is revoked immediately, and it isn’t recoverable otherwise.
• Test keys (_test_) return livemode: false objects and never move real money. Live keys (_live_) do. Keep the two separate in your environment configuration and never charge a live key from a test script.

​

What’s next