Accept a payment with Hosted Checkout

Hosted Checkout is the fastest way to take a payment with Ionic: one API call from your server, a redirect, and you’re done. Ionic hosts the payment page (the card form, Apple Pay, and decline handling that lets the buyer try another card) so you never build payment UI or touch card data.

When to use it

You want to get paid this week, not after building a checkout page.
You’re selling one-time products or services and want a page that just works.
You’re launching subscriptions and want signup and the first charge handled for you.
You want card data and PCI scope nowhere near your servers.

	Best for	Server code
Hosted Checkout (this guide)	The fastest path to a working payment	One API call
Embedded Checkout	The payment form on your own domain	One API call + browser SDK
Payment links	Sharing a URL, no code	None

How it works

Your server creates a Checkout Session
      ↓
The browser redirects to session.url
      ↓
Ionic collects and processes payment
      ↓
Ionic sends checkout.session.completed
      ↓
Your server fulfills the order once

Before you start

Create a test-mode secret key (sk_v1_test_...) in the Dashboard.
Have a success page and a cancel page on your site.

Create Checkout Sessions from your server. Never expose an Ionic secret key in browser code, a mobile app, a public repository, or a client-visible error.

On Node, install the server SDK: typed requests and responses, an idempotency key generated for each call, and automatic retries on transient failures.

npm install @ionicfi/sdk

Every step below also shows raw curl. Finished the Quickstart? Skip to Fulfill from the webhook.

1. Create a Checkout Session

Call POST /v1/checkout/sessions from your server, calculating the amount from prices you trust, never from the browser.

// app/api/checkout/route.ts
import { Ionic } from "@ionicfi/sdk";

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

export async function POST(): Promise<Response> {
  const orderId = "order_1001"; // your pending order's ID

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

  // Save session.id on your order, then hand the hosted URL to the browser.
  return Response.json({ url: session.url });
}

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"
    }
  }'

In this example:

amount is in cents: 15000 is $150.00. USD only for now.
order_1001 is your order’s ID; it threads through Idempotency-Key, client_reference_id, and metadata so the webhook can find the order.
[email protected] pre-fills the buyer’s email (optional).
success_url and cancel_url are pages on your site.
IONIC_SECRET_KEY is an environment variable holding your test-mode secret key.

The line items here are inline: a name, an amount, a currency. If you sell from your Catalog, send a price_id instead and Ionic uses the price you defined there:

{
  "line_items": [
    { "price_id": "price_Pro000000000000000000000", "quantity": 1 }
  ]
}

Inline items are the quickest way to start. Catalog prices keep amounts in one place and are required for subscriptions. The response includes the session and its hosted URL:

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

Save the cs_... ID on your order and use url unchanged; it carries its own token (hcs_...), not the session ID. If the call times out, retry it with the same Idempotency-Key and body to get the original session back. See Idempotency.

Selling a subscription?

Same call with mode: "subscription", where every line item is a recurring Catalog price sharing one billing cadence:

const session = await ionic.checkout.sessions.create({
  "Idempotency-Key": "signup_account_492_monthly",
  mode: "subscription",
  line_items: [
    { price_id: "price_Monthly00000000000000000", quantity: 1 },
  ],
  client_reference_id: "signup_492",
  success_url:
    "https://app.example.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "https://app.example.com/plans",
  metadata: {
    account_id: "account_492",
  },
});

curl https://api.ionicfi.com/v1/checkout/sessions \
  -H "Authorization: Bearer $IONIC_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup_account_492_monthly" \
  -d '{
    "mode": "subscription",
    "line_items": [
      {
        "price_id": "price_Monthly00000000000000000",
        "quantity": 1
      }
    ],
    "client_reference_id": "signup_492",
    "success_url": "https://app.example.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://app.example.com/plans",
    "metadata": {
      "account_id": "account_492"
    }
  }'

price_Monthly00000000000000000 stands in for one of your recurring prices. Pass customer when the buyer already has an Ionic customer record; otherwise the hosted page collects their details and creates one. Everything downstream (redirect, webhook, fulfillment) is identical; see Subscriptions for the recurring lifecycle: renewals, dunning, cancellation.

2. Redirect the buyer

From your page, call your server route and follow the returned URL:

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

if (!response.ok) {
  throw new Error("Could not start checkout");
}

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

When the buyer pays, Ionic replaces the {CHECKOUT_SESSION_ID} placeholder in success_url with the real session ID and redirects. The back button returns the buyer to cancel_url; that and a closed tab both leave the session open and unpaid. On your success page, verify before you show “paid”: send the session_id query value to your backend, retrieve the session with your secret key, and check both status fields.

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

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"

If the session is still open, show a short “Confirming payment” state and poll your backend.

Don’t call POST /v1/checkout/sessions/{id}/confirm here; that endpoint is for Embedded Checkout.

3. Fulfill from the webhook

Subscribe an endpoint to checkout.session.completed and checkout.session.expired (delivered when a session lapses unpaid, after 24 hours by default). The completed event carries the order references you set at creation:

{
  "id": "evt_000000000000000000001001",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_000000000000000000001001",
      "status": "complete",
      "payment_status": "paid",
      "payment_intent_id": "pi_000000000000000000001001",
      "client_reference_id": "order_1001",
      "metadata": {
        "order_id": "order_1001"
      }
    }
  }
}

The event payload above is abbreviated. The full event envelope includes the merchant and mode. Signature verification establishes the delivery’s authenticity; it does not establish which purchase the event belongs to.

Field	Meaning
`event.account`, `event.livemode`	The merchant and mode expected by your application.
`data.object.id`	The CheckoutSession associated with the intended purchase.
`data.object.status`, `payment_status`	A completed payment session is `complete` and `paid`.
`client_reference_id`, `metadata`	Correlation data supplied at creation; not proof of ownership or uniqueness.

Your backend can verify deliveries with webhooks.unwrap() from the server SDK. Signature verification documents the raw-body and header contract. A redirect or browser callback alone does not prove payment. Events can be duplicated or arrive out of order. Your application owns order storage and fulfillment policy under the delivery and acknowledgment contracts.

Developing locally? Webhooks need a URL Ionic can reach. Expose your dev server with a tunnel (for example ngrok or cloudflared), register the tunnel URL as a test-mode endpoint, and pay again. The webhooks quickstart covers endpoint setup.

See it work

Pay with 4111 1111 1111 1111, any future expiration date, and any three-digit CVC. Then check:

The buyer lands on your success page.
Your endpoint receives checkout.session.completed, and the retrieved session is complete and paid.
The payment appears in your Dashboard.

If all three check out, you have a working integration. When you’re ready, go live. To see a decline, create a session whose total is under $1.00; the session stays open and the buyer can retry. More scenarios in Test cards.

Advanced options

The Checkout Sessions reference has the complete request and response contract. Commonly used:

Known customers: pass customer to link the session. See Customers.
Optional items and quantities: optional_items offers add-ons the buyer can select; adjustable_quantity on a line item lets the buyer change the count. Fulfill from the completed session’s line items, not the original cart.
Field collection: collect_config requires contact, billing, or shipping fields.
Button label: submit_type accepts auto, pay, book, or donate.
Expiration: expires_at, 30 minutes to 24 hours from creation; the default is 24 hours.
Capture and reuse: payment_intent_data for supported capture and future-usage behavior.
Metadata: up to 50 keys per session and 20 per line item; non-sensitive values only.
Apple Pay: offered on the hosted page without merchant domain registration. See Apple Pay.
Save a card without a purchase: use a Setup Intent; Checkout Session creation does not accept mode: "setup". See Save cards.

What’s next

Go live

Swap test keys for live keys and launch.

Refund and capture payments

Refund, capture, or cancel a payment.

Embed checkout on your site

Keep buyers on your own domain.

Sell with a payment link

Turn a catalog price into a reusable link you can share.

Payments

Manage payments

Accept a payment with Hosted Checkout

When to use it

How it works

Before you start

1. Create a Checkout Session

Selling a subscription?

2. Redirect the buyer

3. Fulfill from the webhook

See it work

Advanced options

What’s next

Go live

Refund and capture payments

Embed checkout on your site

Sell with a payment link

​When to use it

​How it works

​Before you start

​1. Create a Checkout Session

​Selling a subscription?

​2. Redirect the buyer

​3. Fulfill from the webhook

​See it work

​Advanced options

​What’s next

Go live

Refund and capture payments

Embed checkout on your site

Sell with a payment link

When to use it

How it works

Before you start

1. Create a Checkout Session

Selling a subscription?

2. Redirect the buyer

3. Fulfill from the webhook

See it work

Advanced options

What’s next