Quickstart

This guide gets one hosted checkout payment moving end to end. It uses inline line items so you can integrate first and add catalog objects later.

Prerequisites

A test-mode secret key (sk_v1_test_...), created in the Dashboard.
A backend route that can call Ionic without exposing the secret key to the browser.
A success URL and cancel URL in your application.

Never create checkout sessions directly from browser code with a secret key. Your frontend should call your server, and your server should call Ionic.

If your backend runs Node, install the server SDK. It carries typed request and response shapes for every endpoint, generates an idempotency key for each mutating call, and retries transient failures with backoff. Every step below also shows the raw HTTP call for other stacks.

npm install @ionicfi/sdk

1. Create a session

Create the session from your server.

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

const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });

const session = await ionic.checkout.sessions.create({
  "Idempotency-Key": "order_1001-checkout",
  mode: "payment",
  line_items: [
    {
      name: "Pro onboarding",
      amount: 15000,
      currency: "usd",
      quantity: 1,
    },
  ],
  customer_email: "[email protected]",
  client_reference_id: "order_1001",
  success_url: "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "https://example.com/cart",
  metadata: {
    order_id: "order_1001",
  },
});

curl https://api.ionicfi.com/v1/checkout/sessions \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1001-checkout" \
  -d '{
    "mode": "payment",
    "line_items": [
      {
        "name": "Pro onboarding",
        "amount": 15000,
        "currency": "usd",
        "quantity": 1
      }
    ],
    "customer_email": "[email protected]",
    "client_reference_id": "order_1001",
    "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://example.com/cart",
    "metadata": {
      "order_id": "order_1001"
    }
  }'

amount is in cents: 15000 is $150.00. Repeating the request with the same Idempotency-Key and body returns the original session instead of creating a duplicate; the SDK generates a key per call when you omit the field. The response includes a session id, status fields, line item totals, and a hosted checkout url when the session can be opened by the buyer.

{
  "id": "cs_000000000000000000001001",
  "object": "checkout_session",
  "mode": "payment",
  "status": "open",
  "payment_status": "unpaid",
  "amount_total": 15000,
  "currency": "USD",
  "url": "https://checkout.ionicfi.com/c/hcs_..."
}

2. Redirect the buyer

On your frontend, redirect to the returned url.

const response = await fetch("/api/checkout", {
  method: "POST"
});

const session = await response.json();
window.location.assign(session.url);

3. Verify the result

After the buyer returns to your success page, use the session_id from the URL to look up the session from your server.

const session = await ionic.checkout.sessions.retrieve({
  id: "cs_000000000000000000001001",
});

const paid = session.status === "complete" && session.payment_status === "paid";

curl https://api.ionicfi.com/v1/checkout/sessions/cs_000000000000000000001001 \
  -H "Authorization: Bearer $IONIC_SECRET_KEY"

Treat the redirect as a user experience step, not confirmation of payment. Fulfill from a verified checkout.session.completed webhook only when the session is both complete and paid. The webhook quickstart sets one up in about five minutes.

What to build next

Fulfill orders from the checkout.session.completed webhook; the Hosted Checkout guide shows the handler.
Keep buyers on your own domain with embedded checkout, or compare all three surfaces in Ways to accept payments.
Add products and prices when inline amounts become hard to manage.
Add optional items for add-ons and upgrades at checkout.
Add payment links when the same payment surface should be reused or shared.

Start here

Accept payments

Recurring billing

After the payment

Build commerce

Concepts

Prerequisites

1. Create a session

2. Redirect the buyer

3. Verify the result

What to build next

​Prerequisites

​1. Create a session

​2. Redirect the buyer

​3. Verify the result

​What to build next

Prerequisites

1. Create a session

2. Redirect the buyer

3. Verify the result

What to build next