Authenticate API requests

Base URL

https://lirpay.org/api/v2/integration

Create API keys in the merchant dashboard. Send the public key and secret on every Integration API request.

Send the required headers

Parameter	Type	In	Required	Description
X-Lirpay-Public-Key	string	header	yes	Public key for the selected environment.
X-Lirpay-Secret-Key	string	header	yes	Secret shown once when you create the key.

curl -sS https://lirpay.org/api/v2/integration/account \
  -H "X-Lirpay-Public-Key: lpk_test_a1b2c3d4e5f67890" \
  -H "X-Lirpay-Secret-Key: lsk_test_0123456789abcdef0123456789abcdef"

Send the secret as a bearer token

You can replace X-Lirpay-Secret-Key with the standard Authorization header.

X-Lirpay-Public-Key: lpk_live_a1b2c3d4e5f67890
Authorization: Bearer lsk_live_0123456789abcdef0123456789abcdef

Assign scopes

Scopes limit each key to the operations that its integration needs. Existing keys keep project and payment permissions only.

Parameter	Type	In	Required	Description
projects:read	scope	body	no	Read approved projects and project payment methods.
payments:read	scope	body	no	Read payment links and transactions.
payments:write	scope	body	no	Create and cancel payment links, and refund Telegram Stars payments.
balances:read	scope	body	no	Read balances and ledger entries.
withdrawals:read	scope	body	no	Read methods, create quotes, and read withdrawal history.
withdrawals:write	scope	body	no	Create, cancel, and automate withdrawals. Disabled by default.
conversions:read	scope	body	no	Read pairs, create quotes, and read conversions.
conversions:write	scope	body	no	Execute conversions and manage conversion rules.
webhooks:read	scope	body	no	Read webhook configuration and event history.
webhooks:write	scope	body	no	Configure, test, rotate, and redeliver webhooks.
settings:read	scope	body	no	Read integration settings.
settings:write	scope	body	no	Update integration settings.
reports:read	scope	body	no	Read summary reports.

Use idempotency keys

Send Idempotency-Key on every monetary POST request. Repeating the same key and body returns the stored response.

Reuse the same key only when retrying the same operation
A different body with the same key returns 409 idempotency_conflict
A concurrent request with the same key returns 409 request_in_progress