Telegram Stars + Acquiring

Getting the cost of Stars

Verify a Telegram username and get the acquisition cost and minimum sale price of one star

→ GET /api/stars/price

Request parameters

Parameter	Required	Type	Comment
username	Yes	String	The user's Telegram username

Response parameters

Parameter	Type	Comment
starPrice	Number	The acquisition cost of one star, in RUB
minPrice	Number	The minimum sale price of one star, in RUB (acquisition cost plus the minimum WATA commission)

---

Creating an order

Create an order to purchase stars and get a payment link.

The merchant income is the stars' sale price minus the WATA commission (% of the price) and the stars' acquisition cost.

→ POST /api/stars

Request parameters

Parameter	Required	Type	Comment
username	Yes	String	The user's Telegram username
count	Yes	Number	Number of stars to purchase (must be between 50 and 50,000 units)
amount	Yes	Number	The payment (transaction) amount in rubles for which the payment link will be created. Up to 2 digits after the decimal point for kopecks. Example: 1188.00. Value constraints: minPrice*count <= amount <= minPrice*count*1.5. If the amount exceeds 2,000 RUB, order confirmation is required — see Confirming an order
description	Yes	String	Order description or other details
telegramId	No	Number	The user's Telegram ID
orderId	Yes	String	Order number. It is later used to check the order status
successRedirectUrl	No	String	The store page URL the payer is redirected to if the order payment succeeds
failRedirectUrl	No	String	The store page URL the payer is redirected to if the order payment fails

Response parameters

Parameter	Type	Comment
orderId	String	Order number. It is later used to check the order status
username	String	The user's Telegram username
count	Number	Number of stars to purchase
amount	Number	The payment (transaction) amount in rubles for which the payment link was created. Up to 2 digits after the decimal point for kopecks. Example: 1188.00
price	Number	The stars' acquisition cost, in RUB
commission	Number	The WATA commission, in RUB
description	String	Order description or other details
paymentLink	String	The payment link URL
successRedirectUrl	String	The store page URL the payer is redirected to if the order payment succeeds
failRedirectUrl	String	The store page URL the payer is redirected to if the order payment fails

---

Confirming an order

Confirm the stars delivery.

If confirmation is required, the order is placed in the "Review" status. After confirmation, the order moves to the "Paid" status.

→ POST /api/stars/order/{id}/confirm

Request parameters

Parameter	Required	Type	Comment
id	Yes	String	Order number

---

Cancelling an order

Cancel the stars delivery.

If confirmation is required, the order is placed in the "Review" status. After cancellation, the order moves to the "Refunded" status (funds are returned to the payer).

→ POST /api/stars/order/{id}/reject

Request parameters

Parameter	Required	Type	Comment
id	Yes	String	Order number

---

Checking order status

→ GET /api/stars/order/{id}

Request parameters

Parameter	Required	Type	Comment
id	Yes	String	Order number

Response parameters

Parameter	Type	Comment
orderId	String	Order number
status	String	Order status. Possible values: (1) Pending (awaiting payment) → (2) Review (awaiting merchant order confirmation) → (3.1) Paid (order paid and being fulfilled) OR (3.2) Refunded (order not confirmed, payment returned) → (4.1) Success (order fulfilled) OR (4.2) Fail (error)
username	String	The user's Telegram username
count	Number	Number of stars purchased
amount	Number	The payment (transaction) amount in rubles
description	String	Order details or other information
creationTime	Time	Time in ISO 8601 format (UTC datetime format)
successRedirectUrl	String	The store page URL the payer is redirected to if the order payment succeeds
failRedirectUrl	String	The store page URL the payer is redirected to if the order payment fails

---