Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json
name
string
required

Display name shown on the hosted checkout.

currency
string
required

Three-letter ISO currency code.

amount_total
integer
required

Total in minor units (e.g. cents for USD).

line_items
object[]
required

Price references that make up the order. At least one required.

description
string | null

Optional description shown on the checkout page.

optional_items
object[]

Add-on items the buyer can choose to include.

collect_config
object | null

Contact-information fields to collect at checkout.

custom_fields
object[]

Merchant-defined data fields displayed to the buyer.

submit_type
enum<string> | null

Label for the checkout submit button.

Available options:
pay,
book,
donate

The payment product surface this link represents.

Available options:
one_time,
subscription,
invoice
theme_id
string | null

Theme id to apply to the checkout page.

branding
object | null

Visual overrides for the hosted checkout page.

success_url
string | null

URL to redirect to after a successful payment.

cancel_url
string | null

URL to redirect to if the buyer cancels.

payment_intent_data
object | null

Payment-intent overrides forwarded when a session is created from this link.

inactive_message
string | null

Message shown on the checkout when the link is inactive.

metadata
object

Response

The created payment link.

id
string
required

Payment link identifier (pl_…).

object
enum<string>
required
Available options:
payment_link
merchant_id
string
required
livemode
boolean
required

True for live-mode links; false for test-mode.

active
boolean
required

False when deactivated; the hosted checkout shows an inactive state.

name
string
required
description
string | null
required
url
string
required

The public checkout URL (https://buy.ionicfi.com/c/…).

currency
string
required

Three-letter ISO currency code.

amount_total
integer
required

Total in minor units.

line_items
object[]
required
collect_config
object
required

Specifies which contact fields to collect at checkout and how.

submit_type
enum<string> | null
required
Available options:
pay,
book,
donate
Available options:
one_time,
subscription,
invoice
theme_id
string | null
required
success_url
string | null
required
cancel_url
string | null
required
inactive_message
string | null
required
metadata
object
required
created_at
integer
required

Unix epoch seconds.

updated_at
integer
required
optional_items
object[]

Omitted when the link has no optional add-ons.

custom_fields
object[]

Omitted when the link has no custom fields.

branding
object | null

Omitted when no branding overrides are set.

payment_intent_data
object | null

Omitted when no payment-intent overrides are set.