stripe/resources/generated/topup.rs
1// ======================================
2// This file was automatically generated.
3// ======================================
4
5use crate::client::{Client, Response};
6use crate::ids::TopupId;
7use crate::params::{Expand, Expandable, List, Metadata, Object, Paginable, RangeQuery, Timestamp};
8use crate::resources::{BalanceTransaction, Currency, Source};
9use serde::{Deserialize, Serialize};
10
11/// The resource representing a Stripe "Topup".
12///
13/// For more details see <https://stripe.com/docs/api/topups/object>
14#[derive(Clone, Debug, Default, Deserialize, Serialize)]
15pub struct Topup {
16 /// Unique identifier for the object.
17 pub id: TopupId,
18
19 /// Amount transferred.
20 pub amount: i64,
21
22 /// ID of the balance transaction that describes the impact of this top-up on your account balance.
23 ///
24 /// May not be specified depending on status of top-up.
25 pub balance_transaction: Option<Expandable<BalanceTransaction>>,
26
27 /// Time at which the object was created.
28 ///
29 /// Measured in seconds since the Unix epoch.
30 pub created: Timestamp,
31
32 /// Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
33 ///
34 /// Must be a [supported currency](https://stripe.com/docs/currencies).
35 pub currency: Currency,
36
37 /// An arbitrary string attached to the object.
38 ///
39 /// Often useful for displaying to users.
40 pub description: Option<String>,
41
42 /// Date the funds are expected to arrive in your Stripe account for payouts.
43 ///
44 /// This factors in delays like weekends or bank holidays.
45 /// May not be specified depending on status of top-up.
46 pub expected_availability_date: Option<Timestamp>,
47
48 /// Error code explaining reason for top-up failure if available (see [the errors section](https://stripe.com/docs/api#errors) for a list of codes).
49 pub failure_code: Option<String>,
50
51 /// Message to user further explaining reason for top-up failure if available.
52 pub failure_message: Option<String>,
53
54 /// Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
55 pub livemode: bool,
56
57 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
58 ///
59 /// This can be useful for storing additional information about the object in a structured format.
60 pub metadata: Metadata,
61
62 /// The source field is deprecated.
63 ///
64 /// It might not always be present in the API response.
65 pub source: Option<Source>,
66
67 /// Extra information about a top-up.
68 ///
69 /// This will appear on your source's bank statement.
70 /// It must contain at least one letter.
71 pub statement_descriptor: Option<String>,
72
73 /// The status of the top-up is either `canceled`, `failed`, `pending`, `reversed`, or `succeeded`.
74 pub status: TopupStatus,
75
76 /// A string that identifies this top-up as part of a group.
77 pub transfer_group: Option<String>,
78}
79
80impl Topup {
81 /// Returns a list of top-ups.
82 pub fn list(client: &Client, params: &ListTopups<'_>) -> Response<List<Topup>> {
83 client.get_query("/topups", params)
84 }
85
86 /// Retrieves the details of a top-up that has previously been created.
87 ///
88 /// Supply the unique top-up ID that was returned from your previous request, and Stripe will return the corresponding top-up information.
89 pub fn retrieve(client: &Client, id: &TopupId, expand: &[&str]) -> Response<Topup> {
90 client.get_query(&format!("/topups/{}", id), Expand { expand })
91 }
92
93 /// Updates the metadata of a top-up.
94 ///
95 /// Other top-up details are not editable by design.
96 pub fn update(client: &Client, id: &TopupId, params: UpdateTopup<'_>) -> Response<Topup> {
97 #[allow(clippy::needless_borrows_for_generic_args)]
98 client.post_form(&format!("/topups/{}", id), ¶ms)
99 }
100}
101
102impl Object for Topup {
103 type Id = TopupId;
104 fn id(&self) -> Self::Id {
105 self.id.clone()
106 }
107 fn object(&self) -> &'static str {
108 "topup"
109 }
110}
111
112/// The parameters for `Topup::list`.
113#[derive(Clone, Debug, Serialize, Default)]
114pub struct ListTopups<'a> {
115 /// A positive integer representing how much to transfer.
116 #[serde(skip_serializing_if = "Option::is_none")]
117 pub amount: Option<RangeQuery<Timestamp>>,
118
119 /// A filter on the list, based on the object `created` field.
120 ///
121 /// The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.
122 #[serde(skip_serializing_if = "Option::is_none")]
123 pub created: Option<RangeQuery<Timestamp>>,
124
125 /// A cursor for use in pagination.
126 ///
127 /// `ending_before` is an object ID that defines your place in the list.
128 /// For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
129 #[serde(skip_serializing_if = "Option::is_none")]
130 pub ending_before: Option<TopupId>,
131
132 /// Specifies which fields in the response should be expanded.
133 #[serde(skip_serializing_if = "Expand::is_empty")]
134 pub expand: &'a [&'a str],
135
136 /// A limit on the number of objects to be returned.
137 ///
138 /// Limit can range between 1 and 100, and the default is 10.
139 #[serde(skip_serializing_if = "Option::is_none")]
140 pub limit: Option<u64>,
141
142 /// A cursor for use in pagination.
143 ///
144 /// `starting_after` is an object ID that defines your place in the list.
145 /// For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
146 #[serde(skip_serializing_if = "Option::is_none")]
147 pub starting_after: Option<TopupId>,
148
149 /// Only return top-ups that have the given status.
150 ///
151 /// One of `canceled`, `failed`, `pending` or `succeeded`.
152 #[serde(skip_serializing_if = "Option::is_none")]
153 pub status: Option<TopupStatusFilter>,
154}
155
156impl<'a> ListTopups<'a> {
157 pub fn new() -> Self {
158 ListTopups {
159 amount: Default::default(),
160 created: Default::default(),
161 ending_before: Default::default(),
162 expand: Default::default(),
163 limit: Default::default(),
164 starting_after: Default::default(),
165 status: Default::default(),
166 }
167 }
168}
169impl Paginable for ListTopups<'_> {
170 type O = Topup;
171 fn set_last(&mut self, item: Self::O) {
172 self.starting_after = Some(item.id());
173 }
174}
175/// The parameters for `Topup::update`.
176#[derive(Clone, Debug, Serialize, Default)]
177pub struct UpdateTopup<'a> {
178 /// An arbitrary string attached to the object.
179 ///
180 /// Often useful for displaying to users.
181 #[serde(skip_serializing_if = "Option::is_none")]
182 pub description: Option<&'a str>,
183
184 /// Specifies which fields in the response should be expanded.
185 #[serde(skip_serializing_if = "Expand::is_empty")]
186 pub expand: &'a [&'a str],
187
188 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
189 ///
190 /// This can be useful for storing additional information about the object in a structured format.
191 /// Individual keys can be unset by posting an empty value to them.
192 /// All keys can be unset by posting an empty value to `metadata`.
193 #[serde(skip_serializing_if = "Option::is_none")]
194 pub metadata: Option<Metadata>,
195}
196
197impl<'a> UpdateTopup<'a> {
198 pub fn new() -> Self {
199 UpdateTopup {
200 description: Default::default(),
201 expand: Default::default(),
202 metadata: Default::default(),
203 }
204 }
205}
206
207/// An enum representing the possible values of an `Topup`'s `status` field.
208#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
209#[serde(rename_all = "snake_case")]
210pub enum TopupStatus {
211 Canceled,
212 Failed,
213 Pending,
214 Reversed,
215 Succeeded,
216}
217
218impl TopupStatus {
219 pub fn as_str(self) -> &'static str {
220 match self {
221 TopupStatus::Canceled => "canceled",
222 TopupStatus::Failed => "failed",
223 TopupStatus::Pending => "pending",
224 TopupStatus::Reversed => "reversed",
225 TopupStatus::Succeeded => "succeeded",
226 }
227 }
228}
229
230impl AsRef<str> for TopupStatus {
231 fn as_ref(&self) -> &str {
232 self.as_str()
233 }
234}
235
236impl std::fmt::Display for TopupStatus {
237 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
238 self.as_str().fmt(f)
239 }
240}
241impl std::default::Default for TopupStatus {
242 fn default() -> Self {
243 Self::Canceled
244 }
245}
246
247/// An enum representing the possible values of an `ListTopups`'s `status` field.
248#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
249#[serde(rename_all = "snake_case")]
250pub enum TopupStatusFilter {
251 Canceled,
252 Failed,
253 Pending,
254 Succeeded,
255}
256
257impl TopupStatusFilter {
258 pub fn as_str(self) -> &'static str {
259 match self {
260 TopupStatusFilter::Canceled => "canceled",
261 TopupStatusFilter::Failed => "failed",
262 TopupStatusFilter::Pending => "pending",
263 TopupStatusFilter::Succeeded => "succeeded",
264 }
265 }
266}
267
268impl AsRef<str> for TopupStatusFilter {
269 fn as_ref(&self) -> &str {
270 self.as_str()
271 }
272}
273
274impl std::fmt::Display for TopupStatusFilter {
275 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
276 self.as_str().fmt(f)
277 }
278}
279impl std::default::Default for TopupStatusFilter {
280 fn default() -> Self {
281 Self::Canceled
282 }
283}