square_api_client/api/payments_api.rs
1//! The Payments API lets developers take and manage payments.
2//!
3//! Applications need the following input to take a payment:
4//!
5//! * The amount to charge.
6//!
7//! * The payment recipient. The payment goes to the account identified by the Authorization header
8//! in the API request.
9//!
10//! * The payment source. The source can be a payment token or card on file.
11//!
12//! You can generate a payment token using the Web Payments SDK and the In-App Payments SDK. For
13//! working code examples, see Square Connect API Examples.
14//!
15//! A card on file is a credit card, debit card, or gift card that is associated with a customer.
16//! You can create a customer and add a card on file using Square APIs, the Square Seller Dashboard, or the Square Point of Sale application.
17
18use crate::{
19 config::Configuration,
20 http::client::HttpClient,
21 models::{
22 errors::ApiError, CancelPaymentByIdempotencyKeyRequest,
23 CancelPaymentByIdempotencyKeyResponse, CancelPaymentResponse, CompletePaymentRequest,
24 CompletePaymentResponse, CreatePaymentRequest, CreatePaymentResponse, GetPaymentResponse,
25 ListPaymentsParameters, ListPaymentsResponse, UpdatePaymentRequest, UpdatePaymentResponse,
26 },
27};
28
29const DEFAULT_URI: &str = "/payments";
30
31/// The Payments API lets developers take and manage payments.
32pub struct PaymentsApi {
33 /// App config information
34 config: Configuration,
35 /// HTTP Client for requests to the Payments API endpoints
36 client: HttpClient,
37}
38
39impl PaymentsApi {
40 pub fn new(config: Configuration, client: HttpClient) -> Self {
41 Self { config, client }
42 }
43
44 /// Cancels (voids) a payment.
45 ///
46 /// You can use this endpoint to cancel a payment with the APPROVED `status`.
47 pub async fn cancel_payment(
48 &self,
49 payment_id: &str,
50 ) -> Result<CancelPaymentResponse, ApiError> {
51 let url = format!("{}/{}/cancel", &self.url(), payment_id);
52 let response = self.client.post::<Option<()>>(&url, &None).await?;
53
54 response.deserialize().await
55 }
56
57 /// Cancels (voids) a payment identified by the idempotency key that is specified in the
58 /// request.
59 ///
60 /// Use this method when the status of a `CreatePayment` request is unknown (for example, after
61 /// you send a `CreatePayment` request, a network error occurs and you do not get a response).
62 /// In this case, you can direct Square to cancel the payment using this endpoint. In the
63 /// request, you provide the same idempotency key that you provided in your `CreatePayment`
64 /// request that you want to cancel. After canceling the payment, you can submit your
65 /// `CreatePayment` request again.
66 ///
67 /// Note that if no payment with the specified idempotency key is found, no action is taken and
68 /// the endpoint returns successfully.
69 pub async fn cancel_payment_by_idempotency_key(
70 &self,
71 body: &CancelPaymentByIdempotencyKeyRequest,
72 ) -> Result<CancelPaymentByIdempotencyKeyResponse, ApiError> {
73 let url = format!("{}/cancel", &self.url());
74 let response = self.client.post(&url, body).await?;
75
76 response.deserialize().await
77 }
78
79 /// Completes (captures) a payment.
80 ///
81 /// By default, payments are set to complete immediately after they are created.
82 ///
83 /// You can use this endpoint to complete a payment with the APPROVED `status`.
84 pub async fn complete_payment(
85 &self,
86 payment_id: &str,
87 body: &CompletePaymentRequest,
88 ) -> Result<CompletePaymentResponse, ApiError> {
89 let url = format!("{}/{}/complete", &self.url(), payment_id);
90 let response = self.client.post(&url, body).await?;
91
92 response.deserialize().await
93 }
94
95 /// Creates a payment using the provided source.
96 ///
97 /// You can use this endpoint to charge a card (credit/debit card or Square gift card) or record
98 /// a payment that the seller received outside of Square (cash payment from a buyer or a payment
99 /// that an external entity processed on behalf of the seller).
100 ///
101 /// The endpoint creates a [Payment] object and returns it in the response.
102 pub async fn create_payment(
103 &self,
104 body: &CreatePaymentRequest,
105 ) -> Result<CreatePaymentResponse, ApiError> {
106 let response = self.client.post(&self.url(), body).await?;
107
108 response.deserialize().await
109 }
110
111 /// Retrieves details for a specific payment
112 pub async fn get_payment(&self, payment_id: &str) -> Result<GetPaymentResponse, ApiError> {
113 let url = format!("{}/{}", &self.url(), payment_id);
114 let response = self.client.get(&url).await?;
115
116 response.deserialize().await
117 }
118
119 /// Retrieves a list of payments taken by the account making the request.
120 ///
121 /// Results are eventually consistent, and new payments or changes to payments might take
122 /// several seconds to appear.
123 ///
124 /// The maximum results per page is 100.
125 pub async fn list_payments(
126 &self,
127 params: &ListPaymentsParameters,
128 ) -> Result<ListPaymentsResponse, ApiError> {
129 let url = format!("{}{}", &self.url(), params.to_query_string());
130 let response = self.client.get(&url).await?;
131
132 response.deserialize().await
133 }
134
135 /// Updates a payment with the APPROVED status.
136 ///
137 /// You can update the `amount_money` and `tip_money` using this endpoint.
138 pub async fn update_payment(
139 &self,
140 payment_id: &str,
141 body: &UpdatePaymentRequest,
142 ) -> Result<UpdatePaymentResponse, ApiError> {
143 let url = format!("{}/{}", &self.url(), payment_id);
144 let response = self.client.put(&url, &body).await?;
145
146 response.deserialize().await
147 }
148
149 /// Constructs the basic entity URL including domain and entity path. Any additional path
150 /// elements (e.g. path parameters) will need to be appended to this URL.
151 fn url(&self) -> String {
152 format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
153 }
154}