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/// An amount of Telegram Stars.
171///
172/// `amount` is the integer Star count. `nanostar_amount` is a fractional
173/// component in nanostar units (1 Star = 1,000,000,000 nanostars), present
174/// only in certain transaction contexts.
175#[derive(Debug, Clone, Serialize, Deserialize)]
176pub struct StarAmount {
177    /// Integer Star amount.
178    pub amount: u64,
179    /// Fractional amount in nanostar units (1 Star = 1,000,000,000 nanostars).
180    #[serde(skip_serializing_if = "Option::is_none")]
181    pub nanostar_amount: Option<u32>,
182}
183
184// ─── Revenue withdrawal ───────────────────────────────────────────────────────
185
186/// The state of a revenue withdrawal operation.
187#[derive(Debug, Clone, Serialize, Deserialize)]
188#[serde(tag = "type", rename_all = "snake_case")]
189pub enum RevenueWithdrawalState {
190    /// The withdrawal is in progress.
191    Pending,
192    /// The withdrawal succeeded.
193    Succeeded {
194        /// Date the withdrawal was completed in Unix time.
195        date: i64,
196        /// HTTPS URL to view the transaction details.
197        url: String,
198    },
199    /// The withdrawal failed and the transaction was refunded.
200    Failed,
201}
202
203// Affiliate
204
205/// Information about the affiliate that received a commission via this transaction.
206#[derive(Debug, Clone, Serialize, Deserialize)]
207pub struct AffiliateInfo {
208    /// The bot or user that received the affiliate commission, if applicable.
209    #[serde(skip_serializing_if = "Option::is_none")]
210    pub affiliate_user: Option<User>,
211    /// The chat that received the affiliate commission, if applicable.
212    #[serde(skip_serializing_if = "Option::is_none")]
213    pub affiliate_chat: Option<Chat>,
214    /// Stars received per 1000 Stars received by the affiliate program sponsor.
215    pub commission_per_mille: i64,
216    /// Integer amount of Stars received from the transaction; can be negative for refunds.
217    pub amount: i64,
218    /// Fractional nanostar amount; from -999,999,999 to 999,999,999.
219    #[serde(skip_serializing_if = "Option::is_none")]
220    pub nanostar_amount: Option<i32>,
221}
222
223// Transaction partners
224
225/// The source or recipient of a Star transaction.
226#[derive(Debug, Clone, Serialize, Deserialize)]
227#[serde(tag = "type", rename_all = "snake_case")]
228pub enum TransactionPartner {
229    /// A transaction with a user.
230    User(Box<TransactionPartnerUser>),
231    /// A transaction with a chat.
232    Chat(Box<TransactionPartnerChat>),
233    /// The affiliate program that issued the commission.
234    AffiliateProgram(Box<TransactionPartnerAffiliateProgram>),
235    /// A withdrawal transaction with Fragment.
236    Fragment(Box<TransactionPartnerFragment>),
237    /// A withdrawal transaction to the Telegram Ads platform.
238    TelegramAds,
239    /// A transaction for paid broadcasting.
240    TelegramApi(Box<TransactionPartnerTelegramApi>),
241    /// A transaction with an unknown source or recipient.
242    Other,
243}
244
245/// A transaction with a user.
246#[derive(Debug, Clone, Serialize, Deserialize)]
247pub struct TransactionPartnerUser {
248    /// Type of the transaction.
249    ///
250    /// One of `"invoice_payment"`, `"paid_media_payment"`, `"gift_purchase"`,
251    /// `"premium_purchase"`, or `"business_account_transfer"`.
252    pub transaction_type: String,
253    /// The user involved in the transaction.
254    pub user: User,
255    /// Affiliate commission information; available for invoice and paid media payments.
256    #[serde(skip_serializing_if = "Option::is_none")]
257    pub affiliate: Option<AffiliateInfo>,
258    /// Bot-specified invoice payload; available for `"invoice_payment"` only.
259    #[serde(skip_serializing_if = "Option::is_none")]
260    pub invoice_payload: Option<String>,
261    /// Duration of the paid subscription; available for `"invoice_payment"` only.
262    #[serde(skip_serializing_if = "Option::is_none")]
263    pub subscription_period: Option<i64>,
264    /// Paid media bought by the user; available for `"paid_media_payment"` only.
265    #[serde(skip_serializing_if = "Option::is_none")]
266    pub paid_media: Option<Vec<serde_json::Value>>,
267    /// Bot-specified paid media payload; available for `"paid_media_payment"` only.
268    #[serde(skip_serializing_if = "Option::is_none")]
269    pub paid_media_payload: Option<String>,
270    /// The gift sent to the user; available for `"gift_purchase"` only.
271    #[serde(skip_serializing_if = "Option::is_none")]
272    pub gift: Option<Gift>,
273    /// Months of Premium gifted; available for `"premium_purchase"` only.
274    #[serde(skip_serializing_if = "Option::is_none")]
275    pub premium_subscription_duration: Option<i64>,
276}
277
278/// A transaction with a chat.
279#[derive(Debug, Clone, Serialize, Deserialize)]
280pub struct TransactionPartnerChat {
281    /// The chat involved in the transaction.
282    pub chat: Chat,
283    /// The gift sent to the chat by the bot.
284    #[serde(skip_serializing_if = "Option::is_none")]
285    pub gift: Option<Gift>,
286}
287
288/// The affiliate program that issued the commission received via this transaction.
289#[derive(Debug, Clone, Serialize, Deserialize)]
290pub struct TransactionPartnerAffiliateProgram {
291    /// The bot that sponsored the affiliate program, if applicable.
292    #[serde(skip_serializing_if = "Option::is_none")]
293    pub sponsor_user: Option<User>,
294    /// Stars received by the bot per 1000 Stars received by the program sponsor.
295    pub commission_per_mille: i64,
296}
297
298/// A withdrawal transaction with Fragment.
299#[derive(Debug, Clone, Serialize, Deserialize)]
300pub struct TransactionPartnerFragment {
301    /// State of the transaction if it is outgoing.
302    #[serde(skip_serializing_if = "Option::is_none")]
303    pub withdrawal_state: Option<RevenueWithdrawalState>,
304}
305
306/// A transaction for paid broadcasting.
307#[derive(Debug, Clone, Serialize, Deserialize)]
308pub struct TransactionPartnerTelegramApi {
309    /// Number of successful requests that exceeded regular limits and were billed.
310    pub request_count: i64,
311}
312
313// Star transactions
314
315/// A list of Telegram Star transactions.
316#[derive(Debug, Clone, Serialize, Deserialize)]
317pub struct StarTransactions {
318    /// The list of transactions.
319    pub transactions: Vec<StarTransaction>,
320}
321
322/// A single Telegram Star transaction.
323#[derive(Debug, Clone, Serialize, Deserialize)]
324pub struct StarTransaction {
325    /// Unique transaction identifier.
326    pub id: String,
327    /// Number of Telegram Stars transferred.
328    pub amount: u64,
329    /// Number of 1/1000000000 shares of Telegram Stars transferred.
330    #[serde(skip_serializing_if = "Option::is_none")]
331    pub nanostar_amount: Option<u32>,
332    /// Date the transaction was created, as a Unix timestamp.
333    pub date: i64,
334    /// Source of an incoming transaction.
335    #[serde(skip_serializing_if = "Option::is_none")]
336    pub source: Option<TransactionPartner>,
337    /// Receiver of an outgoing transaction.
338    #[serde(skip_serializing_if = "Option::is_none")]
339    pub receiver: Option<TransactionPartner>,
340}
341
342// Gifts
343
344/// Types of gifts that can be gifted to a user or chat.
345#[derive(Debug, Clone, Serialize, Deserialize)]
346pub struct AcceptedGiftTypes {
347    /// `true` if unlimited regular gifts are accepted.
348    pub unlimited_gifts: bool,
349    /// `true` if limited regular gifts are accepted.
350    pub limited_gifts: bool,
351    /// `true` if unique gifts or gifts upgradable to unique for free are accepted.
352    pub unique_gifts: bool,
353    /// `true` if a Telegram Premium subscription is accepted.
354    pub premium_subscription: bool,
355    /// `true` if transfers of unique gifts from channels are accepted.
356    pub gifts_from_channels: bool,
357}
358
359/// A regular gift owned by a user or chat.
360#[derive(Debug, Clone, Serialize, Deserialize)]
361pub struct OwnedGiftRegular {
362    /// Information about the regular gift.
363    pub gift: Gift,
364    /// Unique identifier of the gift for the bot; for business account gifts only.
365    #[serde(skip_serializing_if = "Option::is_none")]
366    pub owned_gift_id: Option<String>,
367    /// Sender of the gift if it is a known user.
368    #[serde(skip_serializing_if = "Option::is_none")]
369    pub sender_user: Option<User>,
370    /// Date the gift was sent, as a Unix timestamp.
371    pub send_date: i64,
372    /// Text of the message added to the gift.
373    #[serde(skip_serializing_if = "Option::is_none")]
374    pub text: Option<String>,
375    /// Special entities in the text.
376    #[serde(skip_serializing_if = "Option::is_none")]
377    pub entities: Option<Vec<MessageEntity>>,
378    /// `true` if only the gift receiver can see the sender and text.
379    #[serde(skip_serializing_if = "Option::is_none")]
380    pub is_private: Option<bool>,
381    /// `true` if the gift is displayed on the account's profile page.
382    #[serde(skip_serializing_if = "Option::is_none")]
383    pub is_saved: Option<bool>,
384    /// `true` if the gift can be upgraded to a unique gift.
385    #[serde(skip_serializing_if = "Option::is_none")]
386    pub can_be_upgraded: Option<bool>,
387    /// `true` if the gift was refunded and is no longer available.
388    #[serde(skip_serializing_if = "Option::is_none")]
389    pub was_refunded: Option<bool>,
390    /// Stars that can be claimed instead of the gift.
391    #[serde(skip_serializing_if = "Option::is_none")]
392    pub convert_star_count: Option<i64>,
393    /// Stars prepaid for the ability to upgrade the gift.
394    #[serde(skip_serializing_if = "Option::is_none")]
395    pub prepaid_upgrade_star_count: Option<i64>,
396    /// `true` if the upgrade was purchased after the gift was sent.
397    #[serde(skip_serializing_if = "Option::is_none")]
398    pub is_upgrade_separate: Option<bool>,
399    /// Unique number reserved for this gift when upgraded.
400    #[serde(skip_serializing_if = "Option::is_none")]
401    pub unique_gift_number: Option<i64>,
402}
403
404/// A unique gift owned by a user or chat.
405#[derive(Debug, Clone, Serialize, Deserialize)]
406pub struct OwnedGiftUnique {
407    /// Information about the unique gift.
408    pub gift: UniqueGift,
409    /// Unique identifier of the gift for the bot; for business account gifts only.
410    #[serde(skip_serializing_if = "Option::is_none")]
411    pub owned_gift_id: Option<String>,
412    /// Sender of the gift if it is a known user.
413    #[serde(skip_serializing_if = "Option::is_none")]
414    pub sender_user: Option<User>,
415    /// Date the gift was sent, as a Unix timestamp.
416    pub send_date: i64,
417    /// `true` if the gift is displayed on the account's profile page.
418    #[serde(skip_serializing_if = "Option::is_none")]
419    pub is_saved: Option<bool>,
420    /// `true` if the gift can be transferred to another owner.
421    #[serde(skip_serializing_if = "Option::is_none")]
422    pub can_be_transferred: Option<bool>,
423    /// Stars required to transfer the gift.
424    #[serde(skip_serializing_if = "Option::is_none")]
425    pub transfer_star_count: Option<i64>,
426    /// Unix timestamp when the gift can next be transferred.
427    #[serde(skip_serializing_if = "Option::is_none")]
428    pub next_transfer_date: Option<i64>,
429}
430
431/// A gift received and owned by a user or chat.
432#[derive(Debug, Clone, Serialize, Deserialize)]
433#[serde(tag = "type", rename_all = "snake_case")]
434pub enum OwnedGift {
435    /// A regular owned gift.
436    Regular(Box<OwnedGiftUnique>),
437    /// A unique owned gift.
438    Unique(Box<OwnedGiftUnique>),
439}
440
441/// A paginated list of gifts owned by a user or chat.
442#[derive(Debug, Clone, Serialize, Deserialize)]
443pub struct OwnedGifts {
444    /// Total number of gifts owned by the user or chat.
445    pub total_count: i64,
446    /// The list of gifts.
447    pub gifts: Vec<OwnedGift>,
448    /// Offset for the next request; absent if there are no more results.
449    #[serde(skip_serializing_if = "Option::is_none")]
450    pub next_offset: Option<String>,
451}
452
453// Paid media
454
455/// A photo available as paid media.
456#[derive(Debug, Clone, Serialize, Deserialize)]
457pub struct PaidMediaPhoto {
458    /// Available sizes of the photo.
459    pub photo: Vec<PhotoSize>,
460}
461
462/// A preview shown before a user purchases paid media.
463#[derive(Debug, Clone, Serialize, Deserialize)]
464pub struct PaidMediaPreview {
465    /// Media width as defined by the sender.
466    #[serde(skip_serializing_if = "Option::is_none")]
467    pub width: Option<i64>,
468    /// Media height as defined by the sender.
469    #[serde(skip_serializing_if = "Option::is_none")]
470    pub height: Option<i64>,
471    /// Duration of the media in seconds as defined by the sender.
472    #[serde(skip_serializing_if = "Option::is_none")]
473    pub duration: Option<i64>,
474}
475
476/// A live photo available as paid media.
477#[derive(Debug, Clone, Serialize, Deserialize)]
478pub struct PaidMediaLivePhoto {
479    /// The live photo.
480    pub live_photo: crate::file::LivePhoto,
481}
rustigram_types/payments.rs

rustigram_types/
payments.rs
