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.

Pay crypto directly into Bybit

Checkout uses Bybit deposit addresses. Send the exact invoice amount and any required memo/comment. Credit follows a released deposit reported by Bybit. Read GET /payment-methods for platform availability and GET /projects/{id}/payment-methods for project permission and fees. The selected deposit network must also be open on Bybit.

Parameter	Type	In	Required	Description
bsc	BNB	body	no	USDT and exchange-supported USDC on BNB Smart Chain.
ton	GRAM	body	no	USDT and USDE on TON.
litecoin	LTC	body	no	LTC only; no stablecoin rail.
polygon	POL	body	no	USDT and USDC on Polygon.
arbitrum	ARB	body	no	USDT and USDC on Arbitrum One.

For a single method set method_mode: "single" and the matching selected_chain / selected_asset_symbol. Dynamic project links accept ?method=bnb, gram, ltc, pol, or arb. Stablecoins use an explicit pair, for example ?method=arbitrum:USDC. The invoice currency remains USD, EUR, or RUB.

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

Create a checkout or direct Telegram Stars / Robux payment.

API key or OAuth tokenpayments: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.
webhook_url	URL	body	no	Signed event destination for this request. Overrides the deprecated saved URL; retained for retries and redelivery.
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"
}

Exchange minimums. Crypto payments are settled on an exchange, so each coin has a minimum payment (for example about 5.50 USD for GRAM). With method_mode single a lower amount is rejected with HTTP 400 and code: "below_minimum", method and min_amount_usd. With multi the link is created and the response carries a warnings array with the same fields for every method that cannot be used. The merchant payment-methods endpoint and the public checkout expose min_amount_usd (and below_minimum on the checkout) per method.

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 or OAuth tokenpayments: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 or OAuth tokenpayments: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 or OAuth tokenpayments: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.