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}