rustigram_types/
payments.rs

1use crate::chat::Chat;
2use crate::file::PhotoSize;
3use crate::gifts::{Gift, UniqueGift};
4use crate::message::MessageEntity;
5use crate::user::User;
6use serde::{Deserialize, Serialize};
7
8/// A portion of a price — label and amount in the smallest currency unit.
9///
10/// For Telegram Stars (`XTR`) the amount is in whole Stars.
11/// For fiat currencies (e.g. `USD`) the amount is in cents.
12#[derive(Debug, Clone, Serialize, Deserialize)]
13pub struct LabeledPrice {
14    /// Portion label shown to the user.
15    pub label: String,
16    /// Price in the smallest currency units.
17    pub amount: i64,
18}
19
20/// An invoice for a payment inside a message.
21#[derive(Debug, Clone, Serialize, Deserialize)]
22pub struct Invoice {
23    /// Product name.
24    pub title: String,
25    /// Product description.
26    pub description: String,
27    /// Unique bot deep-linking parameter for the invoice.
28    pub start_parameter: String,
29    /// Three-letter ISO 4217 currency code.
30    pub currency: String,
31    /// Total price in the smallest currency unit.
32    pub total_amount: i64,
33}
34
35/// A shipping address provided by the user during checkout.
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct ShippingAddress {
38    /// Two-letter ISO 3166-1 alpha-2 country code.
39    pub country_code: String,
40    /// State, if applicable.
41    pub state: String,
42    /// City name.
43    pub city: String,
44    /// First line of the street address.
45    pub street_line1: String,
46    /// Second line of the street address.
47    pub street_line2: String,
48    /// Post code.
49    pub post_code: String,
50}
51
52/// Information about an order collected from the user during checkout.
53#[derive(Debug, Clone, Serialize, Deserialize)]
54pub struct OrderInfo {
55    /// User's name.
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub name: Option<String>,
58    /// User's phone number.
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub phone_number: Option<String>,
61    /// User's email address.
62    #[serde(skip_serializing_if = "Option::is_none")]
63    pub email: Option<String>,
64    /// User's shipping address.
65    #[serde(skip_serializing_if = "Option::is_none")]
66    pub shipping_address: Option<ShippingAddress>,
67}
68
69/// One shipping option offered to the user during payment.
70#[derive(Debug, Clone, Serialize, Deserialize)]
71pub struct ShippingOption {
72    /// Shipping option identifier.
73    pub id: String,
74    /// Shipping option title.
75    pub title: String,
76    /// List of price portions.
77    pub prices: Vec<LabeledPrice>,
78}
79
80/// Confirmation that a payment was completed successfully.
81///
82/// Delivered inside a [`Message`](crate::message::Message) after the buyer
83/// confirms checkout.
84#[derive(Debug, Clone, Serialize, Deserialize)]
85pub struct SuccessfulPayment {
86    /// Three-letter ISO 4217 currency code.
87    pub currency: String,
88    /// Total price in the smallest currency unit.
89    pub total_amount: i64,
90    /// Bot-specified invoice payload.
91    pub invoice_payload: String,
92    /// Identifier of the shipping option chosen by the user.
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub shipping_option_id: Option<String>,
95    /// Order info provided by the user.
96    #[serde(skip_serializing_if = "Option::is_none")]
97    pub order_info: Option<OrderInfo>,
98    /// Telegram payment charge identifier.
99    pub telegram_payment_charge_id: String,
100    /// Provider payment identifier.
101    pub provider_payment_charge_id: String,
102    /// Expiration date of the subscription, as a Unix timestamp.
103    #[serde(skip_serializing_if = "Option::is_none")]
104    pub subscription_expiration_date: Option<i64>,
105    /// `true` if the payment is recurring.
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub is_recurring: Option<bool>,
108    /// `true` if this is the first payment for a subscription.
109    #[serde(skip_serializing_if = "Option::is_none")]
110    pub is_first_recurring: Option<bool>,
111}
112
113/// Information about a refunded payment.
114#[derive(Debug, Clone, Serialize, Deserialize)]
115pub struct RefundedPayment {
116    /// Three-letter ISO 4217 currency code, or `"XTR"` for Stars.
117    pub currency: String,
118    /// Total refunded price in the smallest currency unit.
119    pub total_amount: i64,
120    /// Bot-specified invoice payload.
121    pub invoice_payload: String,
122    /// Telegram payment charge identifier.
123    pub telegram_payment_charge_id: String,
124    /// Provider payment refund identifier.
125    #[serde(skip_serializing_if = "Option::is_none")]
126    pub provider_payment_charge_id: Option<String>,
127}
128
129/// An incoming shipping query from a user.
130///
131/// Delivered when the invoice has `is_flexible = true`. Respond with
132/// [`answerShippingQuery`](https://core.telegram.org/bots/api#answershippingquery).
133#[derive(Debug, Clone, Serialize, Deserialize)]
134pub struct ShippingQuery {
135    /// Unique query identifier.
136    pub id: String,
137    /// The user who sent the query.
138    pub from: User,
139    /// Bot-specified invoice payload.
140    pub invoice_payload: String,
141    /// User-specified shipping address.
142    pub shipping_address: ShippingAddress,
143}
144
145/// An incoming pre-checkout query.
146///
147/// Sent immediately before the payment confirmation screen. You must respond
148/// with [`answerPreCheckoutQuery`](https://core.telegram.org/bots/api#answerprecheckoutquery)
149/// within **10 seconds**.
150#[derive(Debug, Clone, Serialize, Deserialize)]
151pub struct PreCheckoutQuery {
152    /// Unique query identifier.
153    pub id: String,
154    /// The user who sent the query.
155    pub from: User,
156    /// Three-letter ISO 4217 currency code.
157    pub currency: String,
158    /// Total price in the smallest currency unit.
159    pub total_amount: i64,
160    /// Bot-specified invoice payload.
161    pub invoice_payload: String,
162    /// Identifier of the shipping option chosen by the user.
163    #[serde(skip_serializing_if = "Option::is_none")]
164    pub shipping_option_id: Option<String>,
165    /// Order info provided by the user.
166    #[serde(skip_serializing_if = "Option::is_none")]
167    pub order_info: Option<OrderInfo>,
168}
169
170/// Information about changes to a user payment subscription toward the bot.
171#[derive(Debug, Clone, Serialize, Deserialize)]
172pub struct BotSubscriptionUpdated {
173    /// User who subscribed for payments toward the bot.
174    pub user: User,
175    /// Bot-specified invoice payload.
176    pub invoice_payload: String,
177    /// The new state of the subscription: `"canceled"` if the user canceled
178    /// it, `"active"` if the user re-enabled a previously canceled
179    /// subscription, or `"failed"` if payment for the subscription failed.
180    pub state: String,
181}
182
183/// An amount of Telegram Stars.
184///
185/// `amount` is the integer Star count. `nanostar_amount` is a fractional
186/// component in nanostar units (1 Star = 1,000,000,000 nanostars), present
187/// only in certain transaction contexts.
188#[derive(Debug, Clone, Serialize, Deserialize)]
189pub struct StarAmount {
190    /// Integer Star amount.
191    pub amount: u64,
192    /// Fractional amount in nanostar units (1 Star = 1,000,000,000 nanostars).
193    #[serde(skip_serializing_if = "Option::is_none")]
194    pub nanostar_amount: Option<u32>,
195}
196
197// ─── Revenue withdrawal ───────────────────────────────────────────────────────
198
199/// The state of a revenue withdrawal operation.
200#[derive(Debug, Clone, Serialize, Deserialize)]
201#[serde(tag = "type", rename_all = "snake_case")]
202pub enum RevenueWithdrawalState {
203    /// The withdrawal is in progress.
204    Pending,
205    /// The withdrawal succeeded.
206    Succeeded {
207        /// Date the withdrawal was completed in Unix time.
208        date: i64,
209        /// HTTPS URL to view the transaction details.
210        url: String,
211    },
212    /// The withdrawal failed and the transaction was refunded.
213    Failed,
214}
215
216// Affiliate
217
218/// Information about the affiliate that received a commission via this transaction.
219#[derive(Debug, Clone, Serialize, Deserialize)]
220pub struct AffiliateInfo {
221    /// The bot or user that received the affiliate commission, if applicable.
222    #[serde(skip_serializing_if = "Option::is_none")]
223    pub affiliate_user: Option<User>,
224    /// The chat that received the affiliate commission, if applicable.
225    #[serde(skip_serializing_if = "Option::is_none")]
226    pub affiliate_chat: Option<Chat>,
227    /// Stars received per 1000 Stars received by the affiliate program sponsor.
228    pub commission_per_mille: i64,
229    /// Integer amount of Stars received from the transaction; can be negative for refunds.
230    pub amount: i64,
231    /// Fractional nanostar amount; from -999,999,999 to 999,999,999.
232    #[serde(skip_serializing_if = "Option::is_none")]
233    pub nanostar_amount: Option<i32>,
234}
235
236// Transaction partners
237
238/// The source or recipient of a Star transaction.
239#[derive(Debug, Clone, Serialize, Deserialize)]
240#[serde(tag = "type", rename_all = "snake_case")]
241pub enum TransactionPartner {
242    /// A transaction with a user.
243    User(Box<TransactionPartnerUser>),
244    /// A transaction with a chat.
245    Chat(Box<TransactionPartnerChat>),
246    /// The affiliate program that issued the commission.
247    AffiliateProgram(Box<TransactionPartnerAffiliateProgram>),
248    /// A withdrawal transaction with Fragment.
249    Fragment(Box<TransactionPartnerFragment>),
250    /// A withdrawal transaction to the Telegram Ads platform.
251    TelegramAds,
252    /// A transaction for paid broadcasting.
253    TelegramApi(Box<TransactionPartnerTelegramApi>),
254    /// A transaction with an unknown source or recipient.
255    Other,
256}
257
258/// A transaction with a user.
259#[derive(Debug, Clone, Serialize, Deserialize)]
260pub struct TransactionPartnerUser {
261    /// Type of the transaction.
262    ///
263    /// One of `"invoice_payment"`, `"paid_media_payment"`, `"gift_purchase"`,
264    /// `"premium_purchase"`, or `"business_account_transfer"`.
265    pub transaction_type: String,
266    /// The user involved in the transaction.
267    pub user: User,
268    /// Affiliate commission information; available for invoice and paid media payments.
269    #[serde(skip_serializing_if = "Option::is_none")]
270    pub affiliate: Option<AffiliateInfo>,
271    /// Bot-specified invoice payload; available for `"invoice_payment"` only.
272    #[serde(skip_serializing_if = "Option::is_none")]
273    pub invoice_payload: Option<String>,
274    /// Duration of the paid subscription; available for `"invoice_payment"` only.
275    #[serde(skip_serializing_if = "Option::is_none")]
276    pub subscription_period: Option<i64>,
277    /// Paid media bought by the user; available for `"paid_media_payment"` only.
278    #[serde(skip_serializing_if = "Option::is_none")]
279    pub paid_media: Option<Vec<PaidMedia>>,
280    /// Bot-specified paid media payload; available for `"paid_media_payment"` only.
281    #[serde(skip_serializing_if = "Option::is_none")]
282    pub paid_media_payload: Option<String>,
283    /// The gift sent to the user; available for `"gift_purchase"` only.
284    #[serde(skip_serializing_if = "Option::is_none")]
285    pub gift: Option<Gift>,
286    /// Months of Premium gifted; available for `"premium_purchase"` only.
287    #[serde(skip_serializing_if = "Option::is_none")]
288    pub premium_subscription_duration: Option<i64>,
289}
290
291/// A transaction with a chat.
292#[derive(Debug, Clone, Serialize, Deserialize)]
293pub struct TransactionPartnerChat {
294    /// The chat involved in the transaction.
295    pub chat: Chat,
296    /// The gift sent to the chat by the bot.
297    #[serde(skip_serializing_if = "Option::is_none")]
298    pub gift: Option<Gift>,
299}
300
301/// The affiliate program that issued the commission received via this transaction.
302#[derive(Debug, Clone, Serialize, Deserialize)]
303pub struct TransactionPartnerAffiliateProgram {
304    /// The bot that sponsored the affiliate program, if applicable.
305    #[serde(skip_serializing_if = "Option::is_none")]
306    pub sponsor_user: Option<User>,
307    /// Stars received by the bot per 1000 Stars received by the program sponsor.
308    pub commission_per_mille: i64,
309}
310
311/// A withdrawal transaction with Fragment.
312#[derive(Debug, Clone, Serialize, Deserialize)]
313pub struct TransactionPartnerFragment {
314    /// State of the transaction if it is outgoing.
315    #[serde(skip_serializing_if = "Option::is_none")]
316    pub withdrawal_state: Option<RevenueWithdrawalState>,
317}
318
319/// A transaction for paid broadcasting.
320#[derive(Debug, Clone, Serialize, Deserialize)]
321pub struct TransactionPartnerTelegramApi {
322    /// Number of successful requests that exceeded regular limits and were billed.
323    pub request_count: i64,
324}
325
326// Star transactions
327
328/// A list of Telegram Star transactions.
329#[derive(Debug, Clone, Serialize, Deserialize)]
330pub struct StarTransactions {
331    /// The list of transactions.
332    pub transactions: Vec<StarTransaction>,
333}
334
335/// A single Telegram Star transaction.
336#[derive(Debug, Clone, Serialize, Deserialize)]
337pub struct StarTransaction {
338    /// Unique transaction identifier.
339    pub id: String,
340    /// Number of Telegram Stars transferred.
341    pub amount: u64,
342    /// Number of 1/1000000000 shares of Telegram Stars transferred.
343    #[serde(skip_serializing_if = "Option::is_none")]
344    pub nanostar_amount: Option<u32>,
345    /// Date the transaction was created, as a Unix timestamp.
346    pub date: i64,
347    /// Source of an incoming transaction.
348    #[serde(skip_serializing_if = "Option::is_none")]
349    pub source: Option<TransactionPartner>,
350    /// Receiver of an outgoing transaction.
351    #[serde(skip_serializing_if = "Option::is_none")]
352    pub receiver: Option<TransactionPartner>,
353}
354
355// Gifts
356
357/// Types of gifts that can be gifted to a user or chat.
358///
359/// [`Default`] is every field `false` — accepting nothing — which is the safe
360/// reading when a server omits the object entirely.
361#[derive(Debug, Clone, Default, Serialize, Deserialize)]
362pub struct AcceptedGiftTypes {
363    /// `true` if unlimited regular gifts are accepted.
364    pub unlimited_gifts: bool,
365    /// `true` if limited regular gifts are accepted.
366    pub limited_gifts: bool,
367    /// `true` if unique gifts or gifts upgradable to unique for free are accepted.
368    pub unique_gifts: bool,
369    /// `true` if a Telegram Premium subscription is accepted.
370    pub premium_subscription: bool,
371    /// `true` if transfers of unique gifts from channels are accepted.
372    pub gifts_from_channels: bool,
373}
374
375/// A regular gift owned by a user or chat.
376#[derive(Debug, Clone, Serialize, Deserialize)]
377pub struct OwnedGiftRegular {
378    /// Information about the regular gift.
379    pub gift: Gift,
380    /// Unique identifier of the gift for the bot; for business account gifts only.
381    #[serde(skip_serializing_if = "Option::is_none")]
382    pub owned_gift_id: Option<String>,
383    /// Sender of the gift if it is a known user.
384    #[serde(skip_serializing_if = "Option::is_none")]
385    pub sender_user: Option<User>,
386    /// Date the gift was sent, as a Unix timestamp.
387    pub send_date: i64,
388    /// Text of the message added to the gift.
389    #[serde(skip_serializing_if = "Option::is_none")]
390    pub text: Option<String>,
391    /// Special entities in the text.
392    #[serde(skip_serializing_if = "Option::is_none")]
393    pub entities: Option<Vec<MessageEntity>>,
394    /// `true` if only the gift receiver can see the sender and text.
395    #[serde(skip_serializing_if = "Option::is_none")]
396    pub is_private: Option<bool>,
397    /// `true` if the gift is displayed on the account's profile page.
398    #[serde(skip_serializing_if = "Option::is_none")]
399    pub is_saved: Option<bool>,
400    /// `true` if the gift can be upgraded to a unique gift.
401    #[serde(skip_serializing_if = "Option::is_none")]
402    pub can_be_upgraded: Option<bool>,
403    /// `true` if the gift was refunded and is no longer available.
404    #[serde(skip_serializing_if = "Option::is_none")]
405    pub was_refunded: Option<bool>,
406    /// Stars that can be claimed instead of the gift.
407    #[serde(skip_serializing_if = "Option::is_none")]
408    pub convert_star_count: Option<i64>,
409    /// Stars prepaid for the ability to upgrade the gift.
410    #[serde(skip_serializing_if = "Option::is_none")]
411    pub prepaid_upgrade_star_count: Option<i64>,
412    /// `true` if the upgrade was purchased after the gift was sent.
413    #[serde(skip_serializing_if = "Option::is_none")]
414    pub is_upgrade_separate: Option<bool>,
415    /// Unique number reserved for this gift when upgraded.
416    #[serde(skip_serializing_if = "Option::is_none")]
417    pub unique_gift_number: Option<i64>,
418}
419
420/// A unique gift owned by a user or chat.
421#[derive(Debug, Clone, Serialize, Deserialize)]
422pub struct OwnedGiftUnique {
423    /// Information about the unique gift.
424    pub gift: UniqueGift,
425    /// Unique identifier of the gift for the bot; for business account gifts only.
426    #[serde(skip_serializing_if = "Option::is_none")]
427    pub owned_gift_id: Option<String>,
428    /// Sender of the gift if it is a known user.
429    #[serde(skip_serializing_if = "Option::is_none")]
430    pub sender_user: Option<User>,
431    /// Date the gift was sent, as a Unix timestamp.
432    pub send_date: i64,
433    /// `true` if the gift is displayed on the account's profile page.
434    #[serde(skip_serializing_if = "Option::is_none")]
435    pub is_saved: Option<bool>,
436    /// `true` if the gift can be transferred to another owner.
437    #[serde(skip_serializing_if = "Option::is_none")]
438    pub can_be_transferred: Option<bool>,
439    /// Stars required to transfer the gift.
440    #[serde(skip_serializing_if = "Option::is_none")]
441    pub transfer_star_count: Option<i64>,
442    /// Unix timestamp when the gift can next be transferred.
443    #[serde(skip_serializing_if = "Option::is_none")]
444    pub next_transfer_date: Option<i64>,
445}
446
447/// A gift received and owned by a user or chat.
448#[derive(Debug, Clone, Serialize, Deserialize)]
449#[serde(tag = "type", rename_all = "snake_case")]
450pub enum OwnedGift {
451    /// A regular owned gift.
452    Regular(Box<OwnedGiftRegular>),
453    /// A unique owned gift.
454    Unique(Box<OwnedGiftUnique>),
455}
456
457/// A paginated list of gifts owned by a user or chat.
458#[derive(Debug, Clone, Serialize, Deserialize)]
459pub struct OwnedGifts {
460    /// Total number of gifts owned by the user or chat.
461    pub total_count: i64,
462    /// The list of gifts.
463    pub gifts: Vec<OwnedGift>,
464    /// Offset for the next request; absent if there are no more results.
465    #[serde(skip_serializing_if = "Option::is_none")]
466    pub next_offset: Option<String>,
467}
468
469// Paid media
470
471/// A photo available as paid media.
472#[derive(Debug, Clone, Serialize, Deserialize)]
473pub struct PaidMediaPhoto {
474    /// Available sizes of the photo.
475    pub photo: Vec<PhotoSize>,
476}
477
478/// A preview shown before a user purchases paid media.
479#[derive(Debug, Clone, Serialize, Deserialize)]
480pub struct PaidMediaPreview {
481    /// Media width as defined by the sender.
482    #[serde(skip_serializing_if = "Option::is_none")]
483    pub width: Option<i64>,
484    /// Media height as defined by the sender.
485    #[serde(skip_serializing_if = "Option::is_none")]
486    pub height: Option<i64>,
487    /// Duration of the media in seconds as defined by the sender.
488    #[serde(skip_serializing_if = "Option::is_none")]
489    pub duration: Option<i64>,
490}
491
492/// A live photo available as paid media.
493#[derive(Debug, Clone, Serialize, Deserialize)]
494pub struct PaidMediaLivePhoto {
495    /// The live photo.
496    pub live_photo: crate::file::LivePhoto,
497}
498
499/// A video available as paid media.
500#[derive(Debug, Clone, Serialize, Deserialize)]
501pub struct PaidMediaVideo {
502    /// The video.
503    pub video: crate::file::Video,
504}
505
506/// One item of paid media.
507///
508/// The `preview` variant is what a user sees before purchasing; the others
509/// carry the real media once it has been bought.
510#[derive(Debug, Clone, Serialize, Deserialize)]
511#[serde(tag = "type", rename_all = "snake_case")]
512pub enum PaidMedia {
513    /// A preview shown before purchase.
514    Preview(PaidMediaPreview),
515    /// A photo.
516    Photo(PaidMediaPhoto),
517    /// A video.
518    Video(PaidMediaVideo),
519    /// A live photo.
520    LivePhoto(PaidMediaLivePhoto),
521}
522
523/// Information about paid media attached to a message.
524#[derive(Debug, Clone, Default, Serialize, Deserialize)]
525#[non_exhaustive]
526pub struct PaidMediaInfo {
527    /// Number of Telegram Stars that must be paid to access the media.
528    pub star_count: i64,
529    /// Information about the paid media.
530    pub paid_media: Vec<PaidMedia>,
531}
rustigram_types/payments.rs

rustigram_types/
payments.rs
