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.

What’s next

Define a catalog

Create the products and prices that links reference.

Offer Apple Pay

Payment links show Apple Pay once Ionic enables it on your account.

Go live

Swap test keys for live keys and launch.

Payments

Manage payments

Create a link

Use catalog-backed line items

Fields that shape the buyer experience

Manage links

What happens when a buyer opens a link

What’s next

Define a catalog

Offer Apple Pay

Go live

​Create a link

​Use catalog-backed line items

​Fields that shape the buyer experience

​Manage links

​What happens when a buyer opens a link

​What’s next

Define a catalog

Offer Apple Pay

Go live

Create a link

Use catalog-backed line items

Fields that shape the buyer experience

Manage links

What happens when a buyer opens a link

What’s next