n8n-nodes-telegram-stars-payments

Telegram Stars invoices, pre-checkout answers, and refunds for n8n.

Installation and credentials

Install n8n-nodes-telegram-stars-payments through Settings → Community Nodes
on a self-hosted n8n instance. This package has not been verified by n8n.

Create the package's Telegram Stars Payments API credential. The bot token stays inside the
credential; do not put it in the Request parameter. HTTPS custom API base URLs
are supported. Node.js 22 or later is required.

The original adapter was tested against n8n 2.40.7. The renamed public package
still requires its own installation smoke test before claiming host compatibility.

Operations

Select an operation and supply its parameters in Request (JSON). A JSON
string or an expression returning an object is accepted. Each input item
produces one linked output item. Items execute sequentially, without retries.

Send Invoice

{
  "chat_id": "123456789",
  "title": "One-time purchase",
  "description": "A one-time digital purchase",
  "payload": "order_123",
  "currency": "XTR",
  "provider_token": "",
  "start_parameter": "order_123",
  "prices": [{ "label": "Purchase", "amount": 50 }]
}

Output: { "message_id": 123 }.

This node supports one-time invoices in private chats: a positive numeric chat
ID, XTR, an empty provider token, one positive integer price, and a nonempty
start parameter. Payloads are limited to 128 UTF-8 bytes. Subscriptions, tips,
shipping, customer information, username destinations, and extra fields are
not supported.

Answer Pre-Checkout Query

{ "pre_checkout_query_id": "query_123", "ok": true }

To decline, set ok to false and include a nonempty error_message of at most
200 characters. Omit error_message when accepting. Output: { "ok": true }.

Telegram must receive an answer within 10 seconds of sending the query.
The node's HTTP deadline is 3 seconds per item, including response reading;
upstream processing and execution queue time also consume Telegram's deadline.
Process checkout events immediately, one event per execution.

Refund Star Payment

{
  "user_id": "123456789",
  "telegram_payment_charge_id": "charge_123"
}

Output: { "ok": true }. Use the charge ID from the confirmed payment.

Failure and cancellation contract

API and validation failures are returned on the regular output as an error
object so the workflow can finalize its own durable operation. They do not
throw merely because On Error is set to Stop Workflow; Retry On Fail
does not retry these output items. The node never performs an automatic retry.

Available safe fields are:

• error.request_started: false: input or credential failure before HTTP.
  No payment API call was dispatched.
• error.code: a bounded native system or recognized Telegram code.
• error.error_code: Telegram's numeric error code.
• error.statusCode: upstream HTTP status, retained even for an invalid body.
• error.parameters.retry_after: Telegram's positive rate-limit delay.

Missing fields do not imply success. A timeout, broken connection, oversized
response, or invalid success response after dispatch can have an unknown
outcome. Do not blindly repeat an invoice or refund: the first request may
have taken effect. CHARGE_ALREADY_REFUNDED is not treated as a new successful
refund. Keep the financial state and reconciliation policy in your workflow.

Send/refund HTTP deadlines are 8 seconds per item. Responses are limited to
64 KiB. Redirects are disabled. Raw URLs, tokens, provider descriptions, error
messages, and cancellation reasons are excluded from output.

Execution cancellation aborts the active request, closes response streams,
and stops further items with a safe NodeOperationError. A cancelled request that already
started still requires reconciliation; cancellation does not undo its effects.

The node does not grant purchased goods or verify successful_payment events.
Fulfill a purchase only after receiving a confirmed payment from Telegram.

Development

npm ci
npm run typecheck
npm run lint
npm run build
npm test
npm pack --dry-run

The published artifact contains compiled node files, its SVG icon, this README,
the manifest, and the MIT license. Runtime dependencies are supplied by n8n.

Migration from the private adapter

The node type changed from n8n-nodes-tarolog-stars.tarologStars to
n8n-nodes-telegram-stars-payments.telegramStarsPayments. Existing workflows
must update that type explicitly. Operation names and the Request parameter
are preserved. Create a Telegram Stars Payments API credential and select
it on the new node; the old telegramApi credential is not reused.
No legacy node alias is registered.

API references

• Telegram Stars payments
• sendInvoice
• answerPreCheckoutQuery
• refundStarPayment
• n8n community-node publication requirements

Maintainer: wordpost. License: MIT.