square_api_client/models/
create_payment_request.rs

1//! Request struct for the Create Payment API
2
3use serde::Serialize;
4
5use super::{Address, CashPaymentDetails, ExternalPaymentDetails, Money};
6
7/// This is a model class for CreatePaymentRequest type.
8#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
9pub struct CreatePaymentRequest {
10    /// The ID for the source of funds for this payment. This can be a payment token (card nonce)
11    /// generated by the Square payment form or a card on file made with the Customers API. If
12    /// recording a payment that the seller received outside of Square, specify either "CASH" or
13    /// "EXTERNAL". For more information, see [Take
14    /// Payments](https://developer.squareup.com/docs/payments-api/take-payments).
15    pub source_id: String,
16    /// A unique string that identifies this `CreatePayment` request. Keys can be any valid string
17    /// but must be unique for every `CreatePayment` request.
18    ///
19    /// Note: The number of allowed characters might be less than the stated maximum, if multi-byte
20    /// characters are used.
21    ///
22    /// For more information, see
23    /// [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
24    pub idempotency_key: String,
25    /// The amount of money to accept for this payment, not including `tip_money`.
26    ///
27    /// The amount must be specified in the smallest denomination of the applicable currency (for
28    /// example, US dollar amounts are specified in cents). For more information, see [Working with
29    /// Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).
30    ///
31    /// The currency code must match the currency associated with the business that is accepting the
32    /// payment.
33    pub amount_money: Money,
34    /// The amount designated as a tip, in addition to `amount_money`.
35    ///
36    /// The amount must be specified in the smallest denomination of the applicable currency (for
37    /// example, US dollar amounts are specified in cents). For more information, see [Working with
38    /// Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).
39    ///
40    /// The currency code must match the currency associated with the business that is accepting the payment.
41    pub tip_money: Option<Money>,
42    /// The amount of money that the developer is taking as a fee for facilitating the payment on
43    /// behalf of the seller.
44    ///
45    /// The amount cannot be more than 90% of the total amount of the payment.
46    ///
47    /// The amount must be specified in the smallest denomination of the applicable currency (for
48    /// example, US dollar amounts are specified in cents). For more information, see [Working with
49    /// Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).
50    ///
51    /// The fee currency code must match the currency associated with the seller that is accepting
52    /// the payment. The application must be from a developer account in the same country and using
53    /// the same currency code as the seller.
54    ///
55    /// For more information about the application fee scenario, see [Take Payments and Collect
56    /// Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).
57    ///
58    /// To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. For
59    /// more information, see
60    /// [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).
61    pub app_fee_money: Option<Money>,
62    /// The duration of time after the payment's creation when Square automatically cancels the
63    /// payment. This automatic cancellation applies only to payments that do not reach a terminal
64    /// state (COMPLETED, CANCELED, or FAILED) before the `delay_duration` time period.
65    ///
66    /// This parameter should be specified as a time duration, in RFC 3339 format, with a minimum
67    /// value of 1 minute.
68    ///
69    /// Note: This feature is only supported for card payments. This parameter can only be set for a
70    /// delayed capture payment (`autocomplete=false`).
71    ///
72    /// Default:
73    /// * Card-present payments: "PT36H" (36 hours) from the creation time.
74    /// * Card-not-present payments: "P7D" (7 days) from the creation time.
75    ///
76    /// Example for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S
77    pub delay_duration: Option<String>,
78    /// If set to `true`, this payment will be completed when possible. If set to `false`, this
79    /// payment is held in an approved state until either explicitly completed (captured) or
80    /// canceled (voided). For more information, see [Delayed
81    /// capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).
82    ///
83    /// Default: true
84    pub autocomplete: Option<bool>,
85    /// Associates a previously created order with this payment.
86    pub order_id: Option<String>,
87    /// The [Customer] ID of the customer associated with the payment.
88    ///
89    /// This is required if the `source_id` refers to a card on file created using the Customers
90    /// API.
91    pub customer_id: Option<String>,
92    /// The location ID to associate with the payment. If not specified, the default location is
93    /// used.
94    pub location_id: Option<String>,
95    /// An optional [TeamMember] ID to associate with this payment.
96    pub team_member_id: Option<String>,
97    /// A user-defined ID to associate with the payment.
98    ///
99    /// You can use this field to associate the payment to an entity in an external system (for
100    /// example, you might specify an order ID that is generated by a third-party shopping cart).
101    pub reference_id: Option<String>,
102    /// An identifying token generated by
103    /// [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).
104    /// Verification tokens encapsulate customer device information and 3-D Secure challenge results
105    /// to indicate that Square has verified the buyer identity.
106    ///
107    /// For more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview).
108    pub verification_token: Option<String>,
109    /// If set to `true` and charging a Square Gift Card, a payment might be returned with
110    /// `amount_money` equal to less than what was requested. For example, a request for $20 when
111    /// charging a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You
112    /// might choose to prompt the buyer for an additional payment to cover the remainder or cancel
113    /// the Gift Card payment. This field cannot be `true` when `autocomplete = true`.
114    ///
115    /// For more information, see [Partial amount with Square Gift
116    /// Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).
117    ///
118    /// Default: false
119    pub accept_partial_authorization: Option<bool>,
120    /// The buyer's email address.
121    pub buyer_email_address: Option<String>,
122    /// The buyer's billing address.
123    pub billing_address: Option<Address>,
124    /// The buyer's shipping address.
125    pub shipping_address: Option<Address>,
126    /// An optional note to be entered by the developer when creating a payment.
127    pub note: Option<String>,
128    /// Optional additional payment information to include on the customer's card statement as part
129    /// of the statement description. This can be, for example, an invoice number, ticket number, or
130    /// short description that uniquely identifies the purchase.
131    ///
132    /// Note that the `statement_description_identifier` might get truncated on the statement
133    /// description to fit the required information including the Square identifier (SQ *) and name
134    /// of the seller taking the payment.
135    pub statement_description_identifier: Option<String>,
136    /// Additional details required when recording a cash payment (`source_id` is CASH).
137    pub cash_details: Option<CashPaymentDetails>,
138    /// Additional details required when recording an external payment (`source_id` is EXTERNAL).
139    pub external_details: Option<ExternalPaymentDetails>,
140}