Create and manage payment links

Payment links normally open a LirPay hosted checkout. Preselected Telegram Stars or Robux payments return a direct provider URL. The API key environment determines whether the checkout uses test or live payment state.

POSThttps://lirpay.org/api/v2/integration/payment-links

Create a checkout or direct Telegram Stars / Robux payment.

API key requiredpayments:writeIdempotency-Key required

Parameter	Type	In	Required	Description
Idempotency-Key	string	header	yes	Unique key for this monetary operation. Maximum 255 characters.
display_name	string	body	yes	Label shown on checkout.
amount	decimal string	body	yes	Invoice amount such as 129.00.
currency	string	body	yes	Invoice currency: RUB, USD, or EUR.
project_id	uuid	body	yes	Approved project identifier.
customer_id	string	body	no	Your customer reference.
method_mode	string	body	no	multi by default, or single.
selected_chain	string	body	no	Required when method_mode is single.
selected_asset_symbol	string	body	no	Required when method_mode is single.
link_type	string	body	no	one_time by default, or reusable.
expires_in_minutes	integer	body	no	Positive custom expiration period.

Request

{
  "display_name": "Premium subscription",
  "amount": "129.00",
  "currency": "RUB",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customer_id": "customer_1042",
  "method_mode": "multi",
  "link_type": "one_time"
}

Response

{
  "public_id": "a1b2c3d4e5f67890",
  "payment_link": "https://lirpay.org/pay/a1b2c3d4e5f67890"
}

Headless Telegram Stars

Set method_mode to single, selected_chain to telegram, and selected_asset_symbol to XTR. In LIVE mode the API creates the Bot API invoice immediately and returns its https://t.me/$... URL instead of a lirpay.org checkout URL.

{
  "display_name": "Premium subscription",
  "amount": "129.00",
  "currency": "RUB",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customer_id": "customer_1042",
  "method_mode": "single",
  "selected_chain": "telegram",
  "selected_asset_symbol": "XTR",
  "link_type": "one_time"
}

{
  "public_id": "a1b2c3d4e5f67890",
  "payment_link": "https://t.me/$AbCdEf123",
  "payment_method": "telegram:XTR",
  "stars_amount": 125
}

Send payment_link from your bot. Status checks and webhooks use the returned public_id. With a TEST key, payment succeeds immediately without creating a real invoice; the response has no payment_link and includes status: "succeeded" and test_mode: true.

Headless Robux

Set method_mode to single, selected_chain to roblox, and selected_asset_symbol to ROBUX. In LIVE mode the API creates the gamepass immediately and returns its https://www.roblox.com/game-pass/... URL as payment_link. Also returns checkout_url (hosted LirPay page with Robux already selected) for an on-site <iframe> status UI — Roblox itself blocks embedding of game-pass pages.

{
  "display_name": "Premium subscription",
  "amount": "129.00",
  "currency": "RUB",
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customer_id": "customer_1042",
  "method_mode": "single",
  "selected_chain": "roblox",
  "selected_asset_symbol": "ROBUX",
  "link_type": "one_time"
}

{
  "public_id": "a1b2c3d4e5f67890",
  "payment_link": "https://www.roblox.com/game-pass/1962126448",
  "checkout_url": "https://lirpay.org/pay/a1b2c3d4e5f67890",
  "payment_method": "roblox:ROBUX",
  "roblox_gamepass_id": 1962126448,
  "expected_amount": "1557"
}

Open payment_link for the buyer to purchase. Poll or webhook on public_id. With a TEST key, payment succeeds immediately without creating a real gamepass.

GEThttps://lirpay.org/api/v2/integration/payment-links

List payment links in the current environment.

API key requiredpayments:read

Parameter	Type	In	Required	Description
project_id	uuid	query	no	Filter by project.
sort_by	string	query	no	created_at, amount, status, expires_at, or display_name.
sort_dir	string	query	no	ASC or DESC.
page	integer	query	no	Page number. Defaults to 1.
limit	integer	query	no	Items per page. Maximum 100.

GEThttps://lirpay.org/api/v2/integration/payment-links/{public_id}

Read one payment link and its payment state.

API key requiredpayments:read

Parameter	Type	In	Required	Description
public_id	string	path	yes	Public identifier returned during creation.

Public statuses are active, in_progress, paid, and expired.

POSThttps://lirpay.org/api/v2/integration/payment-links/{public_id}/cancel

Deactivate an unpaid payment link.

API key requiredpayments:writeIdempotency-Key required

Parameter	Type	In	Required	Description
public_id	string	path	yes	Public payment link identifier.
Idempotency-Key	string	header	yes	Unique key for this monetary operation. Maximum 255 characters.

The endpoint returns 409 after payment or after another terminal state.