Payment links

Payment links are reusable hosted payment entry points. They are useful for invoices, quotes, low-code selling, support-assisted checkout, QR codes, and any flow where the buyer should open the same configured payment surface without your app creating a new checkout session first.

Payment link line items are catalog-backed. Create products and prices first, then use price_id in the link.

On Node, npm install @ionicfi/sdk gives you typed calls for every request below; the server SDK guide has details. Each example also shows raw curl.

Create a link

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

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

const link = await ionic.paymentLinks.create({
  "Idempotency-Key": "services_2026_implementation_link",
  name: "Implementation package",
  description: "Fixed-fee onboarding package",
  currency: "usd",
  amount_total: 250000,
  line_items: [{ price_id: "price_Implementation000000000", quantity: 1 }],
  optional_items: [{ price_id: "price_Expedite000000000000", quantity: 1 }],
  submit_type: "pay",
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
  metadata: { campaign: "services_2026" },
});

console.log(link.url); // the shareable link

curl https://api.ionicfi.com/v1/payment_links \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: services_2026_implementation_link" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Implementation package",
    "description": "Fixed-fee onboarding package",
    "currency": "usd",
    "amount_total": 250000,
    "line_items": [
      {
        "price_id": "price_Implementation000000000",
        "quantity": 1
      }
    ],
    "optional_items": [
      {
        "price_id": "price_Expedite000000000000",
        "quantity": 1
      }
    ],
    "submit_type": "pay",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "metadata": {
      "campaign": "services_2026"
    }
  }'

The response includes a shareable url, link totals, active state, timestamps, and the line item configuration used to create buyer checkout sessions.

Use catalog-backed line items

Payment links reference catalog prices.

{
  "name": "Starter subscription",
  "line_items": [
    {
      "price_id": "price_123",
      "quantity": 1
    }
  ],
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel"
}

Catalog-backed links let non-engineering workflows reuse products and prices without changing application code.

Fields that shape the buyer experience

Field	Purpose
`collect_config`	Collection behavior for buyer details.
`custom_fields`	Additional buyer-provided fields.
`optional_items`	Add-ons or cross-sells shown before payment.
`submit_type`	Button intent such as `pay`, `book`, or `donate`.
`link_type`	Product-defined link type for future behavior branching.
`theme_id`	Theme selection when multiple checkout themes exist.
`branding`	Link-specific brand presentation.
`inactive_message`	Message shown when the link is inactive.

Manage links

List, retrieve, and update links:

const links = await ionic.paymentLinks.list();

const link = await ionic.paymentLinks.retrieve({ id: "pl_00000000000001" });

const updated = await ionic.paymentLinks.update({
  id: "pl_00000000000001",
  inactive_message: "This offer has expired.",
});

curl https://api.ionicfi.com/v1/payment_links \
  -H "Authorization: Bearer sk_v1_test_..."

curl https://api.ionicfi.com/v1/payment_links/pl_00000000000001 \
  -H "Authorization: Bearer sk_v1_test_..."

curl -X POST https://api.ionicfi.com/v1/payment_links/pl_00000000000001 \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inactive_message": "This offer has expired."
  }'

Deactivate or reactivate a link with dedicated actions.

await ionic.paymentLinks.deactivate({ id: "pl_00000000000001" });

curl -X POST https://api.ionicfi.com/v1/payment_links/pl_00000000000001/deactivate \
  -H "Authorization: Bearer sk_v1_test_..."

What happens when a buyer opens a link

Ionic-hosted checkout opens the link, shows the payment page, and creates the checkout attempt. Your server does not need to create a session for each visit or handle raw card data.

Payment links and checkout sessions share many concepts, but they are different resources. A link is reusable configuration. A session is one buyer attempt.

Start here

Accept payments

Recurring billing

After the payment

Build commerce

Concepts

Create a link

Use catalog-backed line items

Fields that shape the buyer experience

Manage links

What happens when a buyer opens a link

​Create a link

​Use catalog-backed line items

​Fields that shape the buyer experience

​Manage links

​What happens when a buyer opens a link

Create a link

Use catalog-backed line items

Fields that shape the buyer experience

Manage links

What happens when a buyer opens a link