Quickstart

Take your first payment with Ionic in three steps. Your server creates a checkout session, the buyer pays on a page Ionic hosts, and your server confirms the result. Ionic hosts the card form and keeps card data off your servers, and everything runs in test mode, where no real money moves. Inline line items let you integrate first and add catalog products later. Building something else? Start from the outcome you want:

Design your own checkout

You choose the layout, the fields, and the Pay button. Ionic Blocks supplies the secure card inputs and confirms the payment.

Take card payments at the counter

Send a sale to a terminal from your point-of-sale backend, starting with the simulated terminals in your test account.

Launch subscriptions

Bill recurring prices automatically, with free trials, renewals, and retries handled by Ionic.

Turn your software into a payments platform

Onboard the businesses you serve and take payments for each of them with one set of platform keys.

Prerequisites

A test-mode secret key (sk_v1_test_...) from Developers → API keys. Test keys move no money. See Authentication.
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. Set one up with the webhook quickstart.

What to build next

Fulfill every order once

A signed checkout.session.completed event tells your server when to fulfill. Skip duplicates and fulfill each order once.

Keep buyers on your site

Embed the same checkout inside your page, so customers finish the purchase without leaving your website.

Price once, sell everywhere

Replace inline amounts with products and prices you reuse in checkout, payment links, and subscriptions.

Sell add-ons at checkout

Offer optional items and let buyers adjust quantities on the same hosted page.

Sell with a link or QR code

Turn an offer into a reusable link for sales teams, QR codes, and campaigns. Edit or retire it without a deploy.

Sign up subscribers

Switch the session to subscription mode and sign up recurring customers on the same hosted page.

Compare integrations in Ways to accept payments, or browse what you can build. When your integration works end to end, Going live moves it to real payments.

Start here

Key concepts

Test and go live

Design your own checkout

Take card payments at the counter

Launch subscriptions

Turn your software into a payments platform

Prerequisites

1. Create a session

2. Redirect the buyer

3. Verify the result

What to build next

Fulfill every order once

Keep buyers on your site

Price once, sell everywhere

Sell add-ons at checkout

Sell with a link or QR code

Sign up subscribers

Design your own checkout

Take card payments at the counter

Launch subscriptions

Turn your software into a payments platform

​Prerequisites

​1. Create a session

​2. Redirect the buyer

​3. Verify the result

​What to build next

Fulfill every order once

Keep buyers on your site

Price once, sell everywhere

Sell add-ons at checkout

Sell with a link or QR code

Sign up subscribers

Prerequisites

1. Create a session

2. Redirect the buyer

3. Verify the result

What to build next