stripe/resources/generated/payout.rs
1// ======================================
2// This file was automatically generated.
3// ======================================
4
5use crate::client::{Client, Response};
6use crate::ids::PayoutId;
7use crate::params::{Expand, Expandable, List, Metadata, Object, Paginable, RangeQuery, Timestamp};
8use crate::resources::{BalanceTransaction, Currency, PayoutDestinationUnion};
9use serde::{Deserialize, Serialize};
10
11/// The resource representing a Stripe "Payout".
12///
13/// For more details see <https://stripe.com/docs/api/payouts/object>
14#[derive(Clone, Debug, Default, Deserialize, Serialize)]
15pub struct Payout {
16 /// Unique identifier for the object.
17 pub id: PayoutId,
18
19 /// The amount (in cents (or local equivalent)) that transfers to your bank account or debit card.
20 pub amount: i64,
21
22 /// Date that you can expect the payout to arrive in the bank.
23 ///
24 /// This factors in delays to account for weekends or bank holidays.
25 pub arrival_date: Timestamp,
26
27 /// Returns `true` if the payout is created by an [automated payout schedule](https://stripe.com/docs/payouts#payout-schedule) and `false` if it's [requested manually](https://stripe.com/docs/payouts#manual-payouts).
28 pub automatic: bool,
29
30 /// ID of the balance transaction that describes the impact of this payout on your account balance.
31 pub balance_transaction: Option<Expandable<BalanceTransaction>>,
32
33 /// Time at which the object was created.
34 ///
35 /// Measured in seconds since the Unix epoch.
36 pub created: Timestamp,
37
38 /// Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
39 ///
40 /// Must be a [supported currency](https://stripe.com/docs/currencies).
41 pub currency: Currency,
42
43 /// An arbitrary string attached to the object.
44 ///
45 /// Often useful for displaying to users.
46 pub description: Option<String>,
47
48 /// ID of the bank account or card the payout is sent to.
49 pub destination: Option<Expandable<PayoutDestinationUnion>>,
50
51 /// If the payout fails or cancels, this is the ID of the balance transaction that reverses the initial balance transaction and returns the funds from the failed payout back in your balance.
52 pub failure_balance_transaction: Option<Expandable<BalanceTransaction>>,
53
54 /// Error code that provides a reason for a payout failure, if available.
55 ///
56 /// View our [list of failure codes](https://stripe.com/docs/api#payout_failures).
57 pub failure_code: Option<String>,
58
59 /// Message that provides the reason for a payout failure, if available.
60 pub failure_message: Option<String>,
61
62 /// Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
63 pub livemode: bool,
64
65 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
66 ///
67 /// This can be useful for storing additional information about the object in a structured format.
68 pub metadata: Option<Metadata>,
69
70 /// The method used to send this payout, which can be `standard` or `instant`.
71 ///
72 /// `instant` is supported for payouts to debit cards and bank accounts in certain countries.
73 /// Learn more about [bank support for Instant Payouts](https://stripe.com/docs/payouts/instant-payouts-banks).
74 pub method: String,
75
76 /// If the payout reverses another, this is the ID of the original payout.
77 pub original_payout: Option<Expandable<Payout>>,
78
79 /// If `completed`, you can use the [Balance Transactions API](https://stripe.com/docs/api/balance_transactions/list#balance_transaction_list-payout) to list all balance transactions that are paid out in this payout.
80 pub reconciliation_status: PayoutReconciliationStatus,
81
82 /// If the payout reverses, this is the ID of the payout that reverses this payout.
83 pub reversed_by: Option<Expandable<Payout>>,
84
85 /// The source balance this payout came from, which can be one of the following: `card`, `fpx`, or `bank_account`.
86 pub source_type: String,
87
88 /// Extra information about a payout that displays on the user's bank statement.
89 pub statement_descriptor: Option<String>,
90
91 /// Current status of the payout: `paid`, `pending`, `in_transit`, `canceled` or `failed`.
92 ///
93 /// A payout is `pending` until it's submitted to the bank, when it becomes `in_transit`.
94 /// The status changes to `paid` if the transaction succeeds, or to `failed` or `canceled` (within 5 business days).
95 /// Some payouts that fail might initially show as `paid`, then change to `failed`.
96 pub status: String,
97
98 /// Can be `bank_account` or `card`.
99 #[serde(rename = "type")]
100 pub type_: PayoutType,
101}
102
103impl Payout {
104 /// Returns a list of existing payouts sent to third-party bank accounts or payouts that Stripe sent to you.
105 ///
106 /// The payouts return in sorted order, with the most recently created payouts appearing first.
107 pub fn list(client: &Client, params: &ListPayouts<'_>) -> Response<List<Payout>> {
108 client.get_query("/payouts", params)
109 }
110
111 /// To send funds to your own bank account, create a new payout object.
112 ///
113 /// Your [Stripe balance](https://stripe.com/docs/api#balance) must cover the payout amount.
114 /// If it doesn’t, you receive an “Insufficient Funds” error. If your API key is in test mode, money won’t actually be sent, though every other action occurs as if you’re in live mode. If you create a manual payout on a Stripe account that uses multiple payment source types, you need to specify the source type balance that the payout draws from.
115 /// The [balance object](https://stripe.com/docs/api#balance_object) details available and pending amounts by source type.
116 pub fn create(client: &Client, params: CreatePayout<'_>) -> Response<Payout> {
117 #[allow(clippy::needless_borrows_for_generic_args)]
118 client.post_form("/payouts", ¶ms)
119 }
120
121 /// Retrieves the details of an existing payout.
122 ///
123 /// Supply the unique payout ID from either a payout creation request or the payout list.
124 /// Stripe returns the corresponding payout information.
125 pub fn retrieve(client: &Client, id: &PayoutId, expand: &[&str]) -> Response<Payout> {
126 client.get_query(&format!("/payouts/{}", id), Expand { expand })
127 }
128
129 /// Updates the specified payout by setting the values of the parameters you pass.
130 ///
131 /// We don’t change parameters that you don’t provide.
132 /// This request only accepts the metadata as arguments.
133 pub fn update(client: &Client, id: &PayoutId, params: UpdatePayout<'_>) -> Response<Payout> {
134 #[allow(clippy::needless_borrows_for_generic_args)]
135 client.post_form(&format!("/payouts/{}", id), ¶ms)
136 }
137}
138
139impl Object for Payout {
140 type Id = PayoutId;
141 fn id(&self) -> Self::Id {
142 self.id.clone()
143 }
144 fn object(&self) -> &'static str {
145 "payout"
146 }
147}
148
149/// The parameters for `Payout::create`.
150#[derive(Clone, Debug, Serialize)]
151pub struct CreatePayout<'a> {
152 /// A positive integer in cents representing how much to payout.
153 pub amount: i64,
154
155 /// Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
156 ///
157 /// Must be a [supported currency](https://stripe.com/docs/currencies).
158 pub currency: Currency,
159
160 /// An arbitrary string attached to the object.
161 ///
162 /// Often useful for displaying to users.
163 #[serde(skip_serializing_if = "Option::is_none")]
164 pub description: Option<&'a str>,
165
166 /// The ID of a bank account or a card to send the payout to.
167 ///
168 /// If you don't provide a destination, we use the default external account for the specified currency.
169 #[serde(skip_serializing_if = "Option::is_none")]
170 pub destination: Option<String>,
171
172 /// Specifies which fields in the response should be expanded.
173 #[serde(skip_serializing_if = "Expand::is_empty")]
174 pub expand: &'a [&'a str],
175
176 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
177 ///
178 /// This can be useful for storing additional information about the object in a structured format.
179 /// Individual keys can be unset by posting an empty value to them.
180 /// All keys can be unset by posting an empty value to `metadata`.
181 #[serde(skip_serializing_if = "Option::is_none")]
182 pub metadata: Option<Metadata>,
183
184 /// The method used to send this payout, which is `standard` or `instant`.
185 ///
186 /// We support `instant` for payouts to debit cards and bank accounts in certain countries.
187 /// Learn more about [bank support for Instant Payouts](https://stripe.com/docs/payouts/instant-payouts-banks).
188 #[serde(skip_serializing_if = "Option::is_none")]
189 pub method: Option<PayoutMethod>,
190
191 /// The balance type of your Stripe balance to draw this payout from.
192 ///
193 /// Balances for different payment sources are kept separately.
194 /// You can find the amounts with the Balances API.
195 /// One of `bank_account`, `card`, or `fpx`.
196 #[serde(skip_serializing_if = "Option::is_none")]
197 pub source_type: Option<PayoutSourceType>,
198
199 /// A string that displays on the recipient's bank or card statement (up to 22 characters).
200 ///
201 /// A `statement_descriptor` that's longer than 22 characters return an error.
202 /// Most banks truncate this information and display it inconsistently.
203 /// Some banks might not display it at all.
204 #[serde(skip_serializing_if = "Option::is_none")]
205 pub statement_descriptor: Option<&'a str>,
206}
207
208impl<'a> CreatePayout<'a> {
209 pub fn new(amount: i64, currency: Currency) -> Self {
210 CreatePayout {
211 amount,
212 currency,
213 description: Default::default(),
214 destination: Default::default(),
215 expand: Default::default(),
216 metadata: Default::default(),
217 method: Default::default(),
218 source_type: Default::default(),
219 statement_descriptor: Default::default(),
220 }
221 }
222}
223
224/// The parameters for `Payout::list`.
225#[derive(Clone, Debug, Serialize, Default)]
226pub struct ListPayouts<'a> {
227 #[serde(skip_serializing_if = "Option::is_none")]
228 pub arrival_date: Option<RangeQuery<Timestamp>>,
229
230 #[serde(skip_serializing_if = "Option::is_none")]
231 pub created: Option<RangeQuery<Timestamp>>,
232
233 /// The ID of an external account - only return payouts sent to this external account.
234 #[serde(skip_serializing_if = "Option::is_none")]
235 pub destination: Option<String>,
236
237 /// A cursor for use in pagination.
238 ///
239 /// `ending_before` is an object ID that defines your place in the list.
240 /// 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.
241 #[serde(skip_serializing_if = "Option::is_none")]
242 pub ending_before: Option<PayoutId>,
243
244 /// Specifies which fields in the response should be expanded.
245 #[serde(skip_serializing_if = "Expand::is_empty")]
246 pub expand: &'a [&'a str],
247
248 /// A limit on the number of objects to be returned.
249 ///
250 /// Limit can range between 1 and 100, and the default is 10.
251 #[serde(skip_serializing_if = "Option::is_none")]
252 pub limit: Option<u64>,
253
254 /// A cursor for use in pagination.
255 ///
256 /// `starting_after` is an object ID that defines your place in the list.
257 /// 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.
258 #[serde(skip_serializing_if = "Option::is_none")]
259 pub starting_after: Option<PayoutId>,
260
261 /// Only return payouts that have the given status: `pending`, `paid`, `failed`, or `canceled`.
262 #[serde(skip_serializing_if = "Option::is_none")]
263 pub status: Option<&'a str>,
264}
265
266impl<'a> ListPayouts<'a> {
267 pub fn new() -> Self {
268 ListPayouts {
269 arrival_date: Default::default(),
270 created: Default::default(),
271 destination: Default::default(),
272 ending_before: Default::default(),
273 expand: Default::default(),
274 limit: Default::default(),
275 starting_after: Default::default(),
276 status: Default::default(),
277 }
278 }
279}
280impl Paginable for ListPayouts<'_> {
281 type O = Payout;
282 fn set_last(&mut self, item: Self::O) {
283 self.starting_after = Some(item.id());
284 }
285}
286/// The parameters for `Payout::update`.
287#[derive(Clone, Debug, Serialize, Default)]
288pub struct UpdatePayout<'a> {
289 /// Specifies which fields in the response should be expanded.
290 #[serde(skip_serializing_if = "Expand::is_empty")]
291 pub expand: &'a [&'a str],
292
293 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
294 ///
295 /// This can be useful for storing additional information about the object in a structured format.
296 /// Individual keys can be unset by posting an empty value to them.
297 /// All keys can be unset by posting an empty value to `metadata`.
298 #[serde(skip_serializing_if = "Option::is_none")]
299 pub metadata: Option<Metadata>,
300}
301
302impl<'a> UpdatePayout<'a> {
303 pub fn new() -> Self {
304 UpdatePayout { expand: Default::default(), metadata: Default::default() }
305 }
306}
307
308/// An enum representing the possible values of an `CreatePayout`'s `method` field.
309#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
310#[serde(rename_all = "snake_case")]
311pub enum PayoutMethod {
312 Instant,
313 Standard,
314}
315
316impl PayoutMethod {
317 pub fn as_str(self) -> &'static str {
318 match self {
319 PayoutMethod::Instant => "instant",
320 PayoutMethod::Standard => "standard",
321 }
322 }
323}
324
325impl AsRef<str> for PayoutMethod {
326 fn as_ref(&self) -> &str {
327 self.as_str()
328 }
329}
330
331impl std::fmt::Display for PayoutMethod {
332 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
333 self.as_str().fmt(f)
334 }
335}
336impl std::default::Default for PayoutMethod {
337 fn default() -> Self {
338 Self::Instant
339 }
340}
341
342/// An enum representing the possible values of an `Payout`'s `reconciliation_status` field.
343#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
344#[serde(rename_all = "snake_case")]
345pub enum PayoutReconciliationStatus {
346 Completed,
347 InProgress,
348 NotApplicable,
349}
350
351impl PayoutReconciliationStatus {
352 pub fn as_str(self) -> &'static str {
353 match self {
354 PayoutReconciliationStatus::Completed => "completed",
355 PayoutReconciliationStatus::InProgress => "in_progress",
356 PayoutReconciliationStatus::NotApplicable => "not_applicable",
357 }
358 }
359}
360
361impl AsRef<str> for PayoutReconciliationStatus {
362 fn as_ref(&self) -> &str {
363 self.as_str()
364 }
365}
366
367impl std::fmt::Display for PayoutReconciliationStatus {
368 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
369 self.as_str().fmt(f)
370 }
371}
372impl std::default::Default for PayoutReconciliationStatus {
373 fn default() -> Self {
374 Self::Completed
375 }
376}
377
378/// An enum representing the possible values of an `CreatePayout`'s `source_type` field.
379#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
380#[serde(rename_all = "snake_case")]
381pub enum PayoutSourceType {
382 BankAccount,
383 Card,
384 Fpx,
385}
386
387impl PayoutSourceType {
388 pub fn as_str(self) -> &'static str {
389 match self {
390 PayoutSourceType::BankAccount => "bank_account",
391 PayoutSourceType::Card => "card",
392 PayoutSourceType::Fpx => "fpx",
393 }
394 }
395}
396
397impl AsRef<str> for PayoutSourceType {
398 fn as_ref(&self) -> &str {
399 self.as_str()
400 }
401}
402
403impl std::fmt::Display for PayoutSourceType {
404 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
405 self.as_str().fmt(f)
406 }
407}
408impl std::default::Default for PayoutSourceType {
409 fn default() -> Self {
410 Self::BankAccount
411 }
412}
413
414/// An enum representing the possible values of an `Payout`'s `type` field.
415#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
416#[serde(rename_all = "snake_case")]
417pub enum PayoutType {
418 BankAccount,
419 Card,
420}
421
422impl PayoutType {
423 pub fn as_str(self) -> &'static str {
424 match self {
425 PayoutType::BankAccount => "bank_account",
426 PayoutType::Card => "card",
427 }
428 }
429}
430
431impl AsRef<str> for PayoutType {
432 fn as_ref(&self) -> &str {
433 self.as_str()
434 }
435}
436
437impl std::fmt::Display for PayoutType {
438 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
439 self.as_str().fmt(f)
440 }
441}
442impl std::default::Default for PayoutType {
443 fn default() -> Self {
444 Self::BankAccount
445 }
446}