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}