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    pub name: Option<String>,
57    /// User's phone number.
58    pub phone_number: Option<String>,
59    /// User's email address.
60    pub email: Option<String>,
61    /// User's shipping address.
62    pub shipping_address: Option<ShippingAddress>,
63}
64
65/// One shipping option offered to the user during payment.
66#[derive(Debug, Clone, Serialize, Deserialize)]
67pub struct ShippingOption {
68    /// Shipping option identifier.
69    pub id: String,
70    /// Shipping option title.
71    pub title: String,
72    /// List of price portions.
73    pub prices: Vec<LabeledPrice>,
74}
75
76/// Confirmation that a payment was completed successfully.
77///
78/// Delivered inside a [`Message`](crate::message::Message) after the buyer
79/// confirms checkout.
80#[derive(Debug, Clone, Serialize, Deserialize)]
81pub struct SuccessfulPayment {
82    /// Three-letter ISO 4217 currency code.
83    pub currency: String,
84    /// Total price in the smallest currency unit.
85    pub total_amount: i64,
86    /// Bot-specified invoice payload.
87    pub invoice_payload: String,
88    /// Identifier of the shipping option chosen by the user.
89    pub shipping_option_id: Option<String>,
90    /// Order info provided by the user.
91    pub order_info: Option<OrderInfo>,
92    /// Telegram payment charge identifier.
93    pub telegram_payment_charge_id: String,
94    /// Provider payment identifier.
95    pub provider_payment_charge_id: String,
96    /// Expiration date of the subscription, as a Unix timestamp.
97    pub subscription_expiration_date: Option<i64>,
98    /// `true` if the payment is recurring.
99    pub is_recurring: Option<bool>,
100    /// `true` if this is the first payment for a subscription.
101    pub is_first_recurring: Option<bool>,
102}
103
104/// Information about a refunded payment.
105#[derive(Debug, Clone, Serialize, Deserialize)]
106pub struct RefundedPayment {
107    /// Three-letter ISO 4217 currency code, or `"XTR"` for Stars.
108    pub currency: String,
109    /// Total refunded price in the smallest currency unit.
110    pub total_amount: i64,
111    /// Bot-specified invoice payload.
112    pub invoice_payload: String,
113    /// Telegram payment charge identifier.
114    pub telegram_payment_charge_id: String,
115    /// Provider payment refund identifier.
116    pub provider_payment_charge_id: Option<String>,
117}
118
119/// An incoming shipping query from a user.
120///
121/// Delivered when the invoice has `is_flexible = true`. Respond with
122/// [`answerShippingQuery`](https://core.telegram.org/bots/api#answershippingquery).
123#[derive(Debug, Clone, Serialize, Deserialize)]
124pub struct ShippingQuery {
125    /// Unique query identifier.
126    pub id: String,
127    /// The user who sent the query.
128    pub from: User,
129    /// Bot-specified invoice payload.
130    pub invoice_payload: String,
131    /// User-specified shipping address.
132    pub shipping_address: ShippingAddress,
133}
134
135/// An incoming pre-checkout query.
136///
137/// Sent immediately before the payment confirmation screen. You must respond
138/// with [`answerPreCheckoutQuery`](https://core.telegram.org/bots/api#answerprecheckoutquery)
139/// within **10 seconds**.
140#[derive(Debug, Clone, Serialize, Deserialize)]
141pub struct PreCheckoutQuery {
142    /// Unique query identifier.
143    pub id: String,
144    /// The user who sent the query.
145    pub from: User,
146    /// Three-letter ISO 4217 currency code.
147    pub currency: String,
148    /// Total price in the smallest currency unit.
149    pub total_amount: i64,
150    /// Bot-specified invoice payload.
151    pub invoice_payload: String,
152    /// Identifier of the shipping option chosen by the user.
153    pub shipping_option_id: Option<String>,
154    /// Order info provided by the user.
155    pub order_info: Option<OrderInfo>,
156}
157
158/// An amount of Telegram Stars.
159///
160/// `amount` is the integer Star count. `nanostar_amount` is a fractional
161/// component in nanostar units (1 Star = 1,000,000,000 nanostars), present
162/// only in certain transaction contexts.
163#[derive(Debug, Clone, Serialize, Deserialize)]
164pub struct StarAmount {
165    /// Integer Star amount.
166    pub amount: u64,
167    /// Fractional amount in nanostar units (1 Star = 1,000,000,000 nanostars).
168    pub nanostar_amount: Option<u32>,
169}
170
171// ─── Revenue withdrawal ───────────────────────────────────────────────────────
172
173/// The state of a revenue withdrawal operation.
174#[derive(Debug, Clone, Serialize, Deserialize)]
175#[serde(tag = "type", rename_all = "snake_case")]
176pub enum RevenueWithdrawalState {
177    /// The withdrawal is in progress.
178    Pending,
179    /// The withdrawal succeeded.
180    Succeeded {
181        /// Date the withdrawal was completed in Unix time.
182        date: i64,
183        /// HTTPS URL to view the transaction details.
184        url: String,
185    },
186    /// The withdrawal failed and the transaction was refunded.
187    Failed,
188}
189
190// Affiliate
191
192/// Information about the affiliate that received a commission via this transaction.
193#[derive(Debug, Clone, Serialize, Deserialize)]
194pub struct AffiliateInfo {
195    /// The bot or user that received the affiliate commission, if applicable.
196    #[serde(skip_serializing_if = "Option::is_none")]
197    pub affiliate_user: Option<User>,
198    /// The chat that received the affiliate commission, if applicable.
199    #[serde(skip_serializing_if = "Option::is_none")]
200    pub affiliate_chat: Option<Chat>,
201    /// Stars received per 1000 Stars received by the affiliate program sponsor.
202    pub commission_per_mille: i64,
203    /// Integer amount of Stars received from the transaction; can be negative for refunds.
204    pub amount: i64,
205    /// Fractional nanostar amount; from -999,999,999 to 999,999,999.
206    #[serde(skip_serializing_if = "Option::is_none")]
207    pub nanostar_amount: Option<i32>,
208}
209
210// Transaction partners
211
212/// The source or recipient of a Star transaction.
213#[derive(Debug, Clone, Serialize, Deserialize)]
214#[serde(tag = "type", rename_all = "snake_case")]
215pub enum TransactionPartner {
216    /// A transaction with a user.
217    User(Box<TransactionPartnerUser>),
218    /// A transaction with a chat.
219    Chat(Box<TransactionPartnerChat>),
220    /// The affiliate program that issued the commission.
221    AffiliateProgram(Box<TransactionPartnerAffiliateProgram>),
222    /// A withdrawal transaction with Fragment.
223    Fragment(Box<TransactionPartnerFragment>),
224    /// A withdrawal transaction to the Telegram Ads platform.
225    TelegramAds,
226    /// A transaction for paid broadcasting.
227    TelegramApi(Box<TransactionPartnerTelegramApi>),
228    /// A transaction with an unknown source or recipient.
229    Other,
230}
231
232/// A transaction with a user.
233#[derive(Debug, Clone, Serialize, Deserialize)]
234pub struct TransactionPartnerUser {
235    /// Type of the transaction.
236    ///
237    /// One of `"invoice_payment"`, `"paid_media_payment"`, `"gift_purchase"`,
238    /// `"premium_purchase"`, or `"business_account_transfer"`.
239    pub transaction_type: String,
240    /// The user involved in the transaction.
241    pub user: User,
242    /// Affiliate commission information; available for invoice and paid media payments.
243    #[serde(skip_serializing_if = "Option::is_none")]
244    pub affiliate: Option<AffiliateInfo>,
245    /// Bot-specified invoice payload; available for `"invoice_payment"` only.
246    #[serde(skip_serializing_if = "Option::is_none")]
247    pub invoice_payload: Option<String>,
248    /// Duration of the paid subscription; available for `"invoice_payment"` only.
249    #[serde(skip_serializing_if = "Option::is_none")]
250    pub subscription_period: Option<i64>,
251    /// Paid media bought by the user; available for `"paid_media_payment"` only.
252    #[serde(skip_serializing_if = "Option::is_none")]
253    pub paid_media: Option<Vec<serde_json::Value>>,
254    /// Bot-specified paid media payload; available for `"paid_media_payment"` only.
255    #[serde(skip_serializing_if = "Option::is_none")]
256    pub paid_media_payload: Option<String>,
257    /// The gift sent to the user; available for `"gift_purchase"` only.
258    #[serde(skip_serializing_if = "Option::is_none")]
259    pub gift: Option<Gift>,
260    /// Months of Premium gifted; available for `"premium_purchase"` only.
261    #[serde(skip_serializing_if = "Option::is_none")]
262    pub premium_subscription_duration: Option<i64>,
263}
264
265/// A transaction with a chat.
266#[derive(Debug, Clone, Serialize, Deserialize)]
267pub struct TransactionPartnerChat {
268    /// The chat involved in the transaction.
269    pub chat: Chat,
270    /// The gift sent to the chat by the bot.
271    #[serde(skip_serializing_if = "Option::is_none")]
272    pub gift: Option<Gift>,
273}
274
275/// The affiliate program that issued the commission received via this transaction.
276#[derive(Debug, Clone, Serialize, Deserialize)]
277pub struct TransactionPartnerAffiliateProgram {
278    /// The bot that sponsored the affiliate program, if applicable.
279    #[serde(skip_serializing_if = "Option::is_none")]
280    pub sponsor_user: Option<User>,
281    /// Stars received by the bot per 1000 Stars received by the program sponsor.
282    pub commission_per_mille: i64,
283}
284
285/// A withdrawal transaction with Fragment.
286#[derive(Debug, Clone, Serialize, Deserialize)]
287pub struct TransactionPartnerFragment {
288    /// State of the transaction if it is outgoing.
289    #[serde(skip_serializing_if = "Option::is_none")]
290    pub withdrawal_state: Option<RevenueWithdrawalState>,
291}
292
293/// A transaction for paid broadcasting.
294#[derive(Debug, Clone, Serialize, Deserialize)]
295pub struct TransactionPartnerTelegramApi {
296    /// Number of successful requests that exceeded regular limits and were billed.
297    pub request_count: i64,
298}
299
300// Star transactions
301
302/// A list of Telegram Star transactions.
303#[derive(Debug, Clone, Serialize, Deserialize)]
304pub struct StarTransactions {
305    /// The list of transactions.
306    pub transactions: Vec<StarTransaction>,
307}
308
309/// A single Telegram Star transaction.
310#[derive(Debug, Clone, Serialize, Deserialize)]
311pub struct StarTransaction {
312    /// Unique transaction identifier.
313    pub id: String,
314    /// Number of Telegram Stars transferred.
315    pub amount: u64,
316    /// Number of 1/1000000000 shares of Telegram Stars transferred.
317    pub nanostar_amount: Option<u32>,
318    /// Date the transaction was created, as a Unix timestamp.
319    pub date: i64,
320    /// Source of an incoming transaction.
321    #[serde(skip_serializing_if = "Option::is_none")]
322    pub source: Option<TransactionPartner>,
323    /// Receiver of an outgoing transaction.
324    #[serde(skip_serializing_if = "Option::is_none")]
325    pub receiver: Option<TransactionPartner>,
326}
327
328// Gifts
329
330/// Types of gifts that can be gifted to a user or chat.
331#[derive(Debug, Clone, Serialize, Deserialize)]
332pub struct AcceptedGiftTypes {
333    /// `true` if unlimited regular gifts are accepted.
334    pub unlimited_gifts: bool,
335    /// `true` if limited regular gifts are accepted.
336    pub limited_gifts: bool,
337    /// `true` if unique gifts or gifts upgradable to unique for free are accepted.
338    pub unique_gifts: bool,
339    /// `true` if a Telegram Premium subscription is accepted.
340    pub premium_subscription: bool,
341    /// `true` if transfers of unique gifts from channels are accepted.
342    pub gifts_from_channels: bool,
343}
344
345/// A regular gift owned by a user or chat.
346#[derive(Debug, Clone, Serialize, Deserialize)]
347pub struct OwnedGiftRegular {
348    /// Information about the regular gift.
349    pub gift: Gift,
350    /// Unique identifier of the gift for the bot; for business account gifts only.
351    #[serde(skip_serializing_if = "Option::is_none")]
352    pub owned_gift_id: Option<String>,
353    /// Sender of the gift if it is a known user.
354    #[serde(skip_serializing_if = "Option::is_none")]
355    pub sender_user: Option<User>,
356    /// Date the gift was sent, as a Unix timestamp.
357    pub send_date: i64,
358    /// Text of the message added to the gift.
359    #[serde(skip_serializing_if = "Option::is_none")]
360    pub text: Option<String>,
361    /// Special entities in the text.
362    #[serde(skip_serializing_if = "Option::is_none")]
363    pub entities: Option<Vec<MessageEntity>>,
364    /// `true` if only the gift receiver can see the sender and text.
365    #[serde(skip_serializing_if = "Option::is_none")]
366    pub is_private: Option<bool>,
367    /// `true` if the gift is displayed on the account's profile page.
368    #[serde(skip_serializing_if = "Option::is_none")]
369    pub is_saved: Option<bool>,
370    /// `true` if the gift can be upgraded to a unique gift.
371    #[serde(skip_serializing_if = "Option::is_none")]
372    pub can_be_upgraded: Option<bool>,
373    /// `true` if the gift was refunded and is no longer available.
374    #[serde(skip_serializing_if = "Option::is_none")]
375    pub was_refunded: Option<bool>,
376    /// Stars that can be claimed instead of the gift.
377    #[serde(skip_serializing_if = "Option::is_none")]
378    pub convert_star_count: Option<i64>,
379    /// Stars prepaid for the ability to upgrade the gift.
380    #[serde(skip_serializing_if = "Option::is_none")]
381    pub prepaid_upgrade_star_count: Option<i64>,
382    /// `true` if the upgrade was purchased after the gift was sent.
383    #[serde(skip_serializing_if = "Option::is_none")]
384    pub is_upgrade_separate: Option<bool>,
385    /// Unique number reserved for this gift when upgraded.
386    #[serde(skip_serializing_if = "Option::is_none")]
387    pub unique_gift_number: Option<i64>,
388}
389
390/// A unique gift owned by a user or chat.
391#[derive(Debug, Clone, Serialize, Deserialize)]
392pub struct OwnedGiftUnique {
393    /// Information about the unique gift.
394    pub gift: UniqueGift,
395    /// Unique identifier of the gift for the bot; for business account gifts only.
396    #[serde(skip_serializing_if = "Option::is_none")]
397    pub owned_gift_id: Option<String>,
398    /// Sender of the gift if it is a known user.
399    #[serde(skip_serializing_if = "Option::is_none")]
400    pub sender_user: Option<User>,
401    /// Date the gift was sent, as a Unix timestamp.
402    pub send_date: i64,
403    /// `true` if the gift is displayed on the account's profile page.
404    #[serde(skip_serializing_if = "Option::is_none")]
405    pub is_saved: Option<bool>,
406    /// `true` if the gift can be transferred to another owner.
407    #[serde(skip_serializing_if = "Option::is_none")]
408    pub can_be_transferred: Option<bool>,
409    /// Stars required to transfer the gift.
410    #[serde(skip_serializing_if = "Option::is_none")]
411    pub transfer_star_count: Option<i64>,
412    /// Unix timestamp when the gift can next be transferred.
413    #[serde(skip_serializing_if = "Option::is_none")]
414    pub next_transfer_date: Option<i64>,
415}
416
417/// A gift received and owned by a user or chat.
418#[derive(Debug, Clone, Serialize, Deserialize)]
419#[serde(tag = "type", rename_all = "snake_case")]
420pub enum OwnedGift {
421    /// A regular owned gift.
422    Regular(Box<OwnedGiftUnique>),
423    /// A unique owned gift.
424    Unique(Box<OwnedGiftUnique>),
425}
426
427/// A paginated list of gifts owned by a user or chat.
428#[derive(Debug, Clone, Serialize, Deserialize)]
429pub struct OwnedGifts {
430    /// Total number of gifts owned by the user or chat.
431    pub total_count: i64,
432    /// The list of gifts.
433    pub gifts: Vec<OwnedGift>,
434    /// Offset for the next request; absent if there are no more results.
435    #[serde(skip_serializing_if = "Option::is_none")]
436    pub next_offset: Option<String>,
437}
438
439// Paid media
440
441/// A photo available as paid media.
442#[derive(Debug, Clone, Serialize, Deserialize)]
443pub struct PaidMediaPhoto {
444    /// Available sizes of the photo.
445    pub photo: Vec<PhotoSize>,
446}
447
448/// A preview shown before a user purchases paid media.
449#[derive(Debug, Clone, Serialize, Deserialize)]
450pub struct PaidMediaPreview {
451    /// Media width as defined by the sender.
452    #[serde(skip_serializing_if = "Option::is_none")]
453    pub width: Option<i64>,
454    /// Media height as defined by the sender.
455    #[serde(skip_serializing_if = "Option::is_none")]
456    pub height: Option<i64>,
457    /// Duration of the media in seconds as defined by the sender.
458    #[serde(skip_serializing_if = "Option::is_none")]
459    pub duration: Option<i64>,
460}
rustigram_types/payments.rs

rustigram_types/
payments.rs
