stripe/resources/generated/transfer.rs
1// ======================================
2// This file was automatically generated.
3// ======================================
4
5use crate::client::{Client, Response};
6use crate::ids::{ChargeId, TransferId};
7use crate::params::{Expand, Expandable, List, Metadata, Object, Paginable, RangeQuery, Timestamp};
8use crate::resources::{Account, BalanceTransaction, Charge, Currency, TransferReversal};
9use serde::{Deserialize, Serialize};
10
11/// The resource representing a Stripe "Transfer".
12///
13/// For more details see <https://stripe.com/docs/api/transfers/object>
14#[derive(Clone, Debug, Default, Deserialize, Serialize)]
15pub struct Transfer {
16 /// Unique identifier for the object.
17 pub id: TransferId,
18
19 /// Amount in cents (or local equivalent) to be transferred.
20 pub amount: i64,
21
22 /// Amount in cents (or local equivalent) reversed (can be less than the amount attribute on the transfer if a partial reversal was issued).
23 pub amount_reversed: i64,
24
25 /// Balance transaction that describes the impact of this transfer on your account balance.
26 pub balance_transaction: Option<Expandable<BalanceTransaction>>,
27
28 /// Time that this record of the transfer was first created.
29 pub created: Timestamp,
30
31 /// Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
32 ///
33 /// Must be a [supported currency](https://stripe.com/docs/currencies).
34 pub currency: Currency,
35
36 /// An arbitrary string attached to the object.
37 ///
38 /// Often useful for displaying to users.
39 pub description: Option<String>,
40
41 /// ID of the Stripe account the transfer was sent to.
42 pub destination: Option<Expandable<Account>>,
43
44 /// If the destination is a Stripe account, this will be the ID of the payment that the destination account received for the transfer.
45 #[serde(skip_serializing_if = "Option::is_none")]
46 pub destination_payment: Option<Expandable<Charge>>,
47
48 /// Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
49 pub livemode: bool,
50
51 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
52 ///
53 /// This can be useful for storing additional information about the object in a structured format.
54 pub metadata: Metadata,
55
56 /// A list of reversals that have been applied to the transfer.
57 pub reversals: List<TransferReversal>,
58
59 /// Whether the transfer has been fully reversed.
60 ///
61 /// If the transfer is only partially reversed, this attribute will still be false.
62 pub reversed: bool,
63
64 /// ID of the charge or payment that was used to fund the transfer.
65 ///
66 /// If null, the transfer was funded from the available balance.
67 pub source_transaction: Option<Expandable<Charge>>,
68
69 /// The source balance this transfer came from.
70 ///
71 /// One of `card`, `fpx`, or `bank_account`.
72 #[serde(skip_serializing_if = "Option::is_none")]
73 pub source_type: Option<TransferSourceType>,
74
75 /// A string that identifies this transaction as part of a group.
76 ///
77 /// See the [Connect documentation](https://stripe.com/docs/connect/separate-charges-and-transfers#transfer-options) for details.
78 pub transfer_group: Option<String>,
79}
80
81impl Transfer {
82 /// Returns a list of existing transfers sent to connected accounts.
83 ///
84 /// The transfers are returned in sorted order, with the most recently created transfers appearing first.
85 pub fn list(client: &Client, params: &ListTransfers<'_>) -> Response<List<Transfer>> {
86 client.get_query("/transfers", params)
87 }
88
89 /// To send funds from your Stripe account to a connected account, you create a new transfer object.
90 ///
91 /// Your [Stripe balance](https://stripe.com/docs/api#balance) must be able to cover the transfer amount, or you’ll receive an “Insufficient Funds” error.
92 pub fn create(client: &Client, params: CreateTransfer<'_>) -> Response<Transfer> {
93 #[allow(clippy::needless_borrows_for_generic_args)]
94 client.post_form("/transfers", ¶ms)
95 }
96
97 /// Retrieves the details of an existing transfer.
98 ///
99 /// Supply the unique transfer ID from either a transfer creation request or the transfer list, and Stripe will return the corresponding transfer information.
100 pub fn retrieve(client: &Client, id: &TransferId, expand: &[&str]) -> Response<Transfer> {
101 client.get_query(&format!("/transfers/{}", id), Expand { expand })
102 }
103
104 /// Updates the specified transfer by setting the values of the parameters passed.
105 ///
106 /// Any parameters not provided will be left unchanged. This request accepts only metadata as an argument.
107 pub fn update(
108 client: &Client,
109 id: &TransferId,
110 params: UpdateTransfer<'_>,
111 ) -> Response<Transfer> {
112 #[allow(clippy::needless_borrows_for_generic_args)]
113 client.post_form(&format!("/transfers/{}", id), ¶ms)
114 }
115}
116
117impl Object for Transfer {
118 type Id = TransferId;
119 fn id(&self) -> Self::Id {
120 self.id.clone()
121 }
122 fn object(&self) -> &'static str {
123 "transfer"
124 }
125}
126
127/// The parameters for `Transfer::create`.
128#[derive(Clone, Debug, Serialize)]
129pub struct CreateTransfer<'a> {
130 /// A positive integer in cents (or local equivalent) representing how much to transfer.
131 #[serde(skip_serializing_if = "Option::is_none")]
132 pub amount: Option<i64>,
133
134 /// 3-letter [ISO code for currency](https://stripe.com/docs/payouts).
135 pub currency: Currency,
136
137 /// An arbitrary string attached to the object.
138 ///
139 /// Often useful for displaying to users.
140 #[serde(skip_serializing_if = "Option::is_none")]
141 pub description: Option<&'a str>,
142
143 /// The ID of a connected Stripe account.
144 ///
145 /// [See the Connect documentation](https://stripe.com/docs/connect/separate-charges-and-transfers) for details.
146 pub destination: String,
147
148 /// Specifies which fields in the response should be expanded.
149 #[serde(skip_serializing_if = "Expand::is_empty")]
150 pub expand: &'a [&'a str],
151
152 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
153 ///
154 /// This can be useful for storing additional information about the object in a structured format.
155 /// Individual keys can be unset by posting an empty value to them.
156 /// All keys can be unset by posting an empty value to `metadata`.
157 #[serde(skip_serializing_if = "Option::is_none")]
158 pub metadata: Option<Metadata>,
159
160 /// You can use this parameter to transfer funds from a charge before they are added to your available balance.
161 ///
162 /// A pending balance will transfer immediately but the funds will not become available until the original charge becomes available.
163 /// [See the Connect documentation](https://stripe.com/docs/connect/separate-charges-and-transfers#transfer-availability) for details.
164 #[serde(skip_serializing_if = "Option::is_none")]
165 pub source_transaction: Option<ChargeId>,
166
167 /// The source balance to use for this transfer.
168 ///
169 /// One of `bank_account`, `card`, or `fpx`.
170 /// For most users, this will default to `card`.
171 #[serde(skip_serializing_if = "Option::is_none")]
172 pub source_type: Option<TransferSourceType>,
173
174 /// A string that identifies this transaction as part of a group.
175 ///
176 /// See the [Connect documentation](https://stripe.com/docs/connect/separate-charges-and-transfers#transfer-options) for details.
177 #[serde(skip_serializing_if = "Option::is_none")]
178 pub transfer_group: Option<&'a str>,
179}
180
181impl<'a> CreateTransfer<'a> {
182 pub fn new(currency: Currency, destination: String) -> Self {
183 CreateTransfer {
184 amount: Default::default(),
185 currency,
186 description: Default::default(),
187 destination,
188 expand: Default::default(),
189 metadata: Default::default(),
190 source_transaction: Default::default(),
191 source_type: Default::default(),
192 transfer_group: Default::default(),
193 }
194 }
195}
196
197/// The parameters for `Transfer::list`.
198#[derive(Clone, Debug, Serialize, Default)]
199pub struct ListTransfers<'a> {
200 #[serde(skip_serializing_if = "Option::is_none")]
201 pub created: Option<RangeQuery<Timestamp>>,
202
203 /// Only return transfers for the destination specified by this account ID.
204 #[serde(skip_serializing_if = "Option::is_none")]
205 pub destination: Option<String>,
206
207 /// A cursor for use in pagination.
208 ///
209 /// `ending_before` is an object ID that defines your place in the list.
210 /// 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.
211 #[serde(skip_serializing_if = "Option::is_none")]
212 pub ending_before: Option<TransferId>,
213
214 /// Specifies which fields in the response should be expanded.
215 #[serde(skip_serializing_if = "Expand::is_empty")]
216 pub expand: &'a [&'a str],
217
218 /// A limit on the number of objects to be returned.
219 ///
220 /// Limit can range between 1 and 100, and the default is 10.
221 #[serde(skip_serializing_if = "Option::is_none")]
222 pub limit: Option<u64>,
223
224 /// A cursor for use in pagination.
225 ///
226 /// `starting_after` is an object ID that defines your place in the list.
227 /// 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.
228 #[serde(skip_serializing_if = "Option::is_none")]
229 pub starting_after: Option<TransferId>,
230
231 /// Only return transfers with the specified transfer group.
232 #[serde(skip_serializing_if = "Option::is_none")]
233 pub transfer_group: Option<&'a str>,
234}
235
236impl<'a> ListTransfers<'a> {
237 pub fn new() -> Self {
238 ListTransfers {
239 created: Default::default(),
240 destination: Default::default(),
241 ending_before: Default::default(),
242 expand: Default::default(),
243 limit: Default::default(),
244 starting_after: Default::default(),
245 transfer_group: Default::default(),
246 }
247 }
248}
249impl Paginable for ListTransfers<'_> {
250 type O = Transfer;
251 fn set_last(&mut self, item: Self::O) {
252 self.starting_after = Some(item.id());
253 }
254}
255/// The parameters for `Transfer::update`.
256#[derive(Clone, Debug, Serialize, Default)]
257pub struct UpdateTransfer<'a> {
258 /// An arbitrary string attached to the object.
259 ///
260 /// Often useful for displaying to users.
261 #[serde(skip_serializing_if = "Option::is_none")]
262 pub description: Option<&'a str>,
263
264 /// Specifies which fields in the response should be expanded.
265 #[serde(skip_serializing_if = "Expand::is_empty")]
266 pub expand: &'a [&'a str],
267
268 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
269 ///
270 /// This can be useful for storing additional information about the object in a structured format.
271 /// Individual keys can be unset by posting an empty value to them.
272 /// All keys can be unset by posting an empty value to `metadata`.
273 #[serde(skip_serializing_if = "Option::is_none")]
274 pub metadata: Option<Metadata>,
275}
276
277impl<'a> UpdateTransfer<'a> {
278 pub fn new() -> Self {
279 UpdateTransfer {
280 description: Default::default(),
281 expand: Default::default(),
282 metadata: Default::default(),
283 }
284 }
285}
286
287/// An enum representing the possible values of an `CreateTransfer`'s `source_type` field.
288#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
289#[serde(rename_all = "snake_case")]
290pub enum TransferSourceType {
291 BankAccount,
292 Card,
293 Fpx,
294}
295
296impl TransferSourceType {
297 pub fn as_str(self) -> &'static str {
298 match self {
299 TransferSourceType::BankAccount => "bank_account",
300 TransferSourceType::Card => "card",
301 TransferSourceType::Fpx => "fpx",
302 }
303 }
304}
305
306impl AsRef<str> for TransferSourceType {
307 fn as_ref(&self) -> &str {
308 self.as_str()
309 }
310}
311
312impl std::fmt::Display for TransferSourceType {
313 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
314 self.as_str().fmt(f)
315 }
316}
317impl std::default::Default for TransferSourceType {
318 fn default() -> Self {
319 Self::BankAccount
320 }
321}