rustigram_types/
payments.rs

1use crate::user::User;
2use serde::{Deserialize, Serialize};
3
4#[derive(Debug, Clone, Serialize, Deserialize)]
5/// A portion of a price — label and amount in the smallest currency unit.
6///
7/// For Telegram Stars (`XTR`) the amount is in whole Stars.
8/// For fiat currencies (e.g. `USD`) the amount is in cents.
9pub struct LabeledPrice {
10    /// Portion label shown to the user.
11    pub label: String,
12    /// Price in the smallest currency units.
13    pub amount: i64,
14}
15
16#[derive(Debug, Clone, Serialize, Deserialize)]
17/// An invoice for a payment inside a message.
18pub struct Invoice {
19    /// Product name.
20    pub title: String,
21    /// Product description.
22    pub description: String,
23    /// Unique bot deep-linking parameter for the invoice.
24    pub start_parameter: String,
25    /// Three-letter ISO 4217 currency code.
26    pub currency: String,
27    /// Total price in the smallest currency unit.
28    pub total_amount: i64,
29}
30
31#[derive(Debug, Clone, Serialize, Deserialize)]
32/// A shipping address provided by the user during checkout.
33pub struct ShippingAddress {
34    /// Two-letter ISO 3166-1 alpha-2 country code.
35    pub country_code: String,
36    /// State, if applicable.
37    pub state: String,
38    /// City name.
39    pub city: String,
40    /// First line of the street address.
41    pub street_line1: String,
42    /// Second line of the street address.
43    pub street_line2: String,
44    /// Post code.
45    pub post_code: String,
46}
47
48#[derive(Debug, Clone, Serialize, Deserialize)]
49/// Information about an order collected from the user during checkout.
50pub struct OrderInfo {
51    /// User's name.
52    pub name: Option<String>,
53    /// User's phone number.
54    pub phone_number: Option<String>,
55    /// User's email address.
56    pub email: Option<String>,
57    /// User's shipping address.
58    pub shipping_address: Option<ShippingAddress>,
59}
60
61#[derive(Debug, Clone, Serialize, Deserialize)]
62/// One shipping option offered to the user during payment.
63pub struct ShippingOption {
64    /// Shipping option identifier.
65    pub id: String,
66    /// Shipping option title.
67    pub title: String,
68    /// List of price portions.
69    pub prices: Vec<LabeledPrice>,
70}
71
72#[derive(Debug, Clone, Serialize, Deserialize)]
73/// Confirmation that a payment was completed successfully.
74///
75/// Delivered inside a [`Message`](crate::message::Message) after the buyer
76/// confirms checkout.
77pub struct SuccessfulPayment {
78    /// Three-letter ISO 4217 currency code.
79    pub currency: String,
80    /// Total price in the smallest currency unit.
81    pub total_amount: i64,
82    /// Bot-specified invoice payload.
83    pub invoice_payload: String,
84    /// Identifier of the shipping option chosen by the user.
85    pub shipping_option_id: Option<String>,
86    /// Order info provided by the user.
87    pub order_info: Option<OrderInfo>,
88    /// Telegram payment charge identifier.
89    pub telegram_payment_charge_id: String,
90    /// Provider payment identifier.
91    pub provider_payment_charge_id: String,
92    /// Expiration date of the subscription, as a Unix timestamp.
93    pub subscription_expiration_date: Option<i64>,
94    /// `true` if the payment is recurring.
95    pub is_recurring: Option<bool>,
96    /// `true` if this is the first payment for a subscription.
97    pub is_first_recurring: Option<bool>,
98}
99
100#[derive(Debug, Clone, Serialize, Deserialize)]
101/// Information about a refunded payment.
102pub struct RefundedPayment {
103    /// Three-letter ISO 4217 currency code, or `"XTR"` for Stars.
104    pub currency: String,
105    /// Total refunded price in the smallest currency unit.
106    pub total_amount: i64,
107    /// Bot-specified invoice payload.
108    pub invoice_payload: String,
109    /// Telegram payment charge identifier.
110    pub telegram_payment_charge_id: String,
111    /// Provider payment refund identifier.
112    pub provider_payment_charge_id: Option<String>,
113}
114
115#[derive(Debug, Clone, Serialize, Deserialize)]
116/// An incoming shipping query from a user.
117///
118/// Delivered when the invoice has `is_flexible = true`. Respond with
119/// [`answerShippingQuery`](https://core.telegram.org/bots/api#answershippingquery).
120pub struct ShippingQuery {
121    /// Unique query identifier.
122    pub id: String,
123    /// The user who sent the query.
124    pub from: User,
125    /// Bot-specified invoice payload.
126    pub invoice_payload: String,
127    /// User-specified shipping address.
128    pub shipping_address: ShippingAddress,
129}
130
131#[derive(Debug, Clone, Serialize, Deserialize)]
132/// An incoming pre-checkout query.
133///
134/// Sent immediately before the payment confirmation screen. You must respond
135/// with [`answerPreCheckoutQuery`](https://core.telegram.org/bots/api#answerprecheckoutquery)
136/// within **10 seconds**.
137pub struct PreCheckoutQuery {
138    /// Unique query identifier.
139    pub id: String,
140    /// The user who sent the query.
141    pub from: User,
142    /// Three-letter ISO 4217 currency code.
143    pub currency: String,
144    /// Total price in the smallest currency unit.
145    pub total_amount: i64,
146    /// Bot-specified invoice payload.
147    pub invoice_payload: String,
148    /// Identifier of the shipping option chosen by the user.
149    pub shipping_option_id: Option<String>,
150    /// Order info provided by the user.
151    pub order_info: Option<OrderInfo>,
152}
153
154#[derive(Debug, Clone, Serialize, Deserialize)]
155/// A list of Telegram Star transactions.
156pub struct StarTransactions {
157    /// The list of transactions.
158    pub transactions: Vec<StarTransaction>,
159}
160
161#[derive(Debug, Clone, Serialize, Deserialize)]
162/// A single Telegram Star transaction.
163pub struct StarTransaction {
164    /// Unique transaction identifier.
165    pub id: String,
166    /// Number of Telegram Stars transferred.
167    pub amount: u64,
168    /// Number of 1/1000000000 shares of Telegram Stars transferred.
169    pub nanostar_amount: Option<u32>,
170    /// Date the transaction was created, as a Unix timestamp.
171    pub date: i64,
172    /// Source of the transaction (for incoming transactions).
173    pub source: Option<serde_json::Value>,
174    /// Receiver of the transaction (for outgoing transactions).
175    pub receiver: Option<serde_json::Value>,
176}
177
178#[derive(Debug, Clone, Serialize, Deserialize)]
179/// An amount of Telegram Stars.
180///
181/// `amount` is the integer Star count. `nanostar_amount` is a fractional
182/// component in nanostar units (1 Star = 1,000,000,000 nanostars), present
183/// only in certain transaction contexts.
184pub struct StarAmount {
185    /// Integer Star amount.
186    pub amount: u64,
187    /// Fractional amount in nanostar units (1 Star = 1,000,000,000 nanostars).
188    pub nanostar_amount: Option<u32>,
189}
rustigram_types/payments.rs

rustigram_types/
payments.rs
