square.rb 7.0.0.20201118 → 9.1.1.20210317

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b369570f3d13e26bc325eb51c619e0beb0b102fcf2165e833772903161db7a9b
-  data.tar.gz: f085f244216551f94863464ec50c3ae2ca46520c2aad30082de005dd5a3a6153
+  metadata.gz: 5daa9230376e0d7e260342e846b5118b92e12aa89fe226ad0df404c5aed13dfa
+  data.tar.gz: c0ba7b58ac6d2ae2d511344c66bdc4b670aef159e4a20045bfd8d8b160e00649
 SHA512:
-  metadata.gz: 50996f5d00d2a7f52950fdf63ff3089bd70f90e523fcf588796bc0e3d07d08d298eee2444dc155e5abb6ed15f893e3181c8dd42d4e81c03fd8feaff623ef27fe
-  data.tar.gz: d59a431601b9ff93f851dc8c10413e4b121e5ba77c0c5d4c7bddd0492e0a57c2fbeafadae38c546b4b5a50b664674d3c31193ed344f74966a4399aba0211ef58
+  metadata.gz: f78aa71da656d92d0aee4afa1af82d7c783bdf37bead5ec7a8f007ea84131e6457c3d413d4cec15cee4b2f15de7a7afd399c32d8c8a331b82ec5902a610c823d
+  data.tar.gz: e9d14b674b48660e2b499e07e730fe818447aedad773fe063d2a40b28286a7f4296d93efd0a9e310dae4c56032c7f377809555c993979207e28e544466fd5503

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2020 Square, Inc.
+Copyright 2121 Square, Inc.
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

data/README.md

@@ -78,7 +78,6 @@ gem 'square.rb'
 * [O Auth]
 
 ### Deprecated APIs
-* [V1 Locations]
 * [V1 Employees]
 * [V1 Transactions]
 * [V1 Items]
@@ -197,6 +196,15 @@ client = Square::Client.new(
     environment: 'production'
 )
 ```
+
+- To set a custom environment provide a `custom_url`, and set environment to `custom`:
+
+```ruby
+client = Square::Client.new(
+    access_token:'ACCESS TOKEN HERE',
+    environment: 'custom',
+    custom_url: 'https://your.customdomain.com'
+)
  
 ### Get an Instance of an API object and call its methods
 
@@ -296,7 +304,7 @@ You can also use the Square API to create applications or services that work wit
 [Cash Drawers]: doc/api/cash-drawers.md
 [Customer Groups]: doc/api/customer-groups.md
 [Customer Segments]: doc/api/customer-segments.md
-[Bank Accounts]: doc/api/bank-accounts
+[Bank Accounts]: doc/api/bank-accounts.md
 [Payments]: doc/api/payments.md
 [Checkout]: doc/api/checkout.md
 [Catalog]: doc/api/catalog.md
@@ -315,7 +323,6 @@ You can also use the Square API to create applications or services that work wit
 [Subscriptions]: doc/api/subscriptions.md
 [Mobile Authorization]: doc/api/mobile-authorization.md
 [O Auth]: doc/api/o-auth.md
-[V1 Locations]: doc/api/v1-locations.md
 [V1 Employees]: doc/api/v1-employees.md
 [V1 Transactions]: doc/api/v1-transactions.md
 [V1 Items]: doc/api/v1-items.md

data/lib/square.rb

@@ -31,10 +31,8 @@ require_relative 'square/configuration.rb'
 require_relative 'square/api/base_api.rb'
 require_relative 'square/api/mobile_authorization_api.rb'
 require_relative 'square/api/o_auth_api.rb'
-require_relative 'square/api/v1_locations_api.rb'
 require_relative 'square/api/v1_employees_api.rb'
 require_relative 'square/api/v1_transactions_api.rb'
-require_relative 'square/api/v1_items_api.rb'
 require_relative 'square/api/apple_pay_api.rb'
 require_relative 'square/api/bank_accounts_api.rb'
 require_relative 'square/api/bookings_api.rb'

data/lib/square/api/apple_pay_api.rb

@@ -5,17 +5,18 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Activates a domain for use with Web Apple Pay and Square. A validation
-    # will be performed on this domain by Apple to ensure is it properly set up
+    # Activates a domain for use with Apple Pay on the Web and Square. A
+    # validation
+    # is performed on this domain by Apple to ensure that it is properly set up
     # as
     # an Apple Pay enabled domain.
     # This endpoint provides an easy way for platform developers to bulk
     # activate
-    # Web Apple Pay with Square for merchants using their platform.
-    # To learn more about Apple Pay on Web see the Apple Pay section in the
-    # [Square Payment Form
-    # Walkthrough](https://developer.squareup.com/docs/payment-form/payment-form
-    # -walkthrough).
+    # Apple Pay on the Web with Square for merchants using their platform.
+    # To learn more about Web Apple Pay, see
+    # [Add the Apple Pay on the Web
+    # Button](https://developer.squareup.com/docs/payment-form/add-digital-walle
+    # ts/apple-pay).
     # @param [RegisterDomainRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.

data/lib/square/api/base_api.rb

@@ -8,7 +8,7 @@ module Square
       @http_call_back = http_call_back
 
       @global_headers = {
-        'user-agent' => 'Square-Ruby-SDK/7.0.0.20201118',
+        'user-agent' => 'Square-Ruby-SDK/9.1.1.20210317',
         'Square-Version' => config.square_version
       }
     end

data/lib/square/api/bookings_api.rb

@@ -262,5 +262,47 @@ module Square
         _response, data: decoded, errors: _errors
       )
     end
+
+    # Cancels an existing booking.
+    # @param [String] booking_id Required parameter: The ID of the
+    # [Booking](#type-booking) object representing the to-be-cancelled
+    # booking.
+    # @param [CancelBookingRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [CancelBookingResponse Hash] response from the API call
+    def cancel_booking(booking_id:,
+                       body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/bookings/{booking_id}/cancel'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'booking_id' => { 'value' => booking_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'content-type' => 'application/json; charset=utf-8'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers,
+        parameters: body.to_json
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
   end
 end

data/lib/square/api/catalog_api.rb

@@ -251,16 +251,23 @@ module Square
     # `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.  The legal values are taken from the
     # CatalogObjectType enum: `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`,
     # `TAX`, `MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.
+    # @param [Long] catalog_version Optional parameter: The specific version of
+    # the catalog objects to be included in the response.  This allows you to
+    # retrieve historical versions of objects. The specified version value is
+    # matched against the [CatalogObject](#type-catalogobject)s' `version`
+    # attribute.
     # @return [ListCatalogResponse Hash] response from the API call
     def list_catalog(cursor: nil,
-                     types: nil)
+                     types: nil,
+                     catalog_version: nil)
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/catalog/list'
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
         'cursor' => cursor,
-        'types' => types
+        'types' => types,
+        'catalog_version' => catalog_version
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -382,9 +389,15 @@ module Square
     # response contains a `CatalogItemVariation`, its parent `CatalogItem` will
     # be returned in the `related_objects` field of the response.  Default
     # value: `false`
+    # @param [Long] catalog_version Optional parameter: Requests objects as of a
+    # specific version of the catalog. This allows you to retrieve historical
+    # versions of objects. The value to retrieve a specific version of an object
+    # can be found in the version field of
+    # [CatalogObject](#type-catalogobject)s.
     # @return [RetrieveCatalogObjectResponse Hash] response from the API call
     def retrieve_catalog_object(object_id:,
-                                include_related_objects: false)
+                                include_related_objects: false,
+                                catalog_version: nil)
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/catalog/object/{object_id}'
@@ -394,7 +407,8 @@ module Square
       )
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
-        'include_related_objects' => include_related_objects
+        'include_related_objects' => include_related_objects,
+        'catalog_version' => catalog_version
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -419,10 +433,10 @@ module Square
       )
     end
 
-    # Searches for [CatalogObject](#type-CatalogObject) of any types against
+    # Searches for [CatalogObject](#type-CatalogObject) of any type by matching
     # supported search attribute values,
     # excluding custom attribute values on items or item variations, against one
-    # or more of the specified query expressions,
+    # or more of the specified query expressions.
     # This (`SearchCatalogObjects`) endpoint differs from the
     # [SearchCatalogItems](#endpoint-Catalog-SearchCatalogItems)
     # endpoint in the following aspects:
@@ -472,7 +486,7 @@ module Square
     # Searches for catalog items or item variations by matching supported search
     # attribute values, including
     # custom attribute values, against one or more of the specified query
-    # expressions,
+    # expressions.
     # This (`SearchCatalogItems`) endpoint differs from the
     # [SearchCatalogObjects](#endpoint-Catalog-SearchCatalogObjects)
     # endpoint in the following aspects:

data/lib/square/api/checkout_api.rb

@@ -5,8 +5,8 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Links a `checkoutId` to a `checkout_page_url` that customers will
-    # be directed to in order to provide their payment information using a
+    # Links a `checkoutId` to a `checkout_page_url` that customers are
+    # directed to in order to provide their payment information using a
     # payment processing workflow hosted on connect.squareup.com.
     # @param [String] location_id Required parameter: The ID of the business
     # location to associate the checkout with.

data/lib/square/api/disputes_api.rb

@@ -5,20 +5,19 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Returns a list of disputes associated
-    # with a particular account.
+    # Returns a list of disputes associated with a particular account.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
-    # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for the original query. For more information, see
-    # [Paginating](https://developer.squareup.com/docs/basics/api101/pagination)
+    # a previous call to this endpoint. Provide this cursor to retrieve the next
+    # set of results for the original query. For more information, see
+    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
     # .
     # @param [DisputeState] states Optional parameter: The dispute states to
     # filter the result. If not specified, the endpoint returns all open
-    # disputes (dispute status is not `INQUIRY_CLOSED`, `WON`, or `LOST`).
+    # disputes (the dispute status is not `INQUIRY_CLOSED`, `WON`, or `LOST`).
     # @param [String] location_id Optional parameter: The ID of the location for
-    # which to return  a list of disputes. If not specified, the endpoint
-    # returns all open disputes (dispute status is not `INQUIRY_CLOSED`, `WON`,
-    # or  `LOST`) associated with all locations.
+    # which to return a list of disputes. If not specified, the endpoint returns
+    # all open disputes (the dispute status is not `INQUIRY_CLOSED`, `WON`, or
+    # `LOST`) associated with all locations.
     # @return [ListDisputesResponse Hash] response from the API call
     def list_disputes(cursor: nil,
                       states: nil,
@@ -55,7 +54,7 @@ module Square
       )
     end
 
-    # Returns details of a specific dispute.
+    # Returns details about a specific dispute.
     # @param [String] dispute_id Required parameter: The ID of the dispute you
     # want more details about.
     # @return [RetrieveDisputeResponse Hash] response from the API call
@@ -90,14 +89,14 @@ module Square
       )
     end
 
-    # Accepts loss on a dispute. Square returns
-    # the disputed amount to the cardholder and updates the
-    # dispute state to ACCEPTED.
-    # Square debits the disputed amount from the seller’s Square
-    # account. If the Square account balance does not have
-    # sufficient funds, Square debits the associated bank account.
-    # @param [String] dispute_id Required parameter: ID of the dispute you want
-    # to accept.
+    # Accepts the loss on a dispute. Square returns the disputed amount to the
+    # cardholder and
+    # updates the dispute state to ACCEPTED.
+    # Square debits the disputed amount from the seller’s Square account. If the
+    # Square account
+    # does not have sufficient funds, Square debits the associated bank account.
+    # @param [String] dispute_id Required parameter: The ID of the dispute you
+    # want to accept.
     # @return [AcceptDisputeResponse Hash] response from the API call
     def accept_dispute(dispute_id:)
       # Prepare query url.
@@ -165,8 +164,8 @@ module Square
     end
 
     # Removes specified evidence from a dispute.
-    # Square does not send the bank any evidence that
-    # is removed. Also, you cannot remove evidence after
+    # Square does not send the bank any evidence that is removed. Also, you
+    # cannot remove evidence after
     # submitting it to the bank using
     # [SubmitEvidence](https://developer.squareup.com/docs/reference/square/disp
     # utes-api/submit-evidence).
@@ -210,8 +209,8 @@ module Square
 
     # Returns the specific evidence metadata associated with a specific dispute.
     # You must maintain a copy of the evidence you upload if you want to
-    # reference it later. You cannot download the evidence
-    # after you upload it.
+    # reference it later. You cannot
+    # download the evidence after you upload it.
     # @param [String] dispute_id Required parameter: The ID of the dispute that
     # you want to retrieve evidence from.
     # @param [String] evidence_id Required parameter: The ID of the evidence to
@@ -251,13 +250,13 @@ module Square
     end
 
     # Uploads a file to use as evidence in a dispute challenge. The endpoint
-    # accepts
-    # HTTP multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG,
-    # and TIFF formats.
-    # @param [String] dispute_id Required parameter: ID of the dispute you want
-    # to upload evidence for.
+    # accepts HTTP
+    # multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG, and TIFF
+    # formats.
+    # @param [String] dispute_id Required parameter: The ID of the dispute you
+    # want to upload evidence for.
     # @param [CreateDisputeEvidenceFileRequest] request Optional parameter:
-    # Defines parameters for a CreateDisputeEvidenceFile request.
+    # Defines the parameters for a `CreateDisputeEvidenceFile` request.
     # @param [File | UploadIO] image_file Optional parameter: Example:
     # @return [CreateDisputeEvidenceFileResponse Hash] response from the API call
     def create_dispute_evidence_file(dispute_id:,
@@ -358,16 +357,15 @@ module Square
 
     # Submits evidence to the cardholder's bank.
     # Before submitting evidence, Square compiles all available evidence. This
-    # includes
-    # evidence uploaded using the
+    # includes evidence uploaded
+    # using the
     # [CreateDisputeEvidenceFile](https://developer.squareup.com/docs/reference/
     # square/disputes-api/create-dispute-evidence-file) and
     # [CreateDisputeEvidenceText](https://developer.squareup.com/docs/reference/
-    # square/disputes-api/create-dispute-evidence-text) endpoints,
-    # and evidence automatically provided by Square, when
-    # available.
-    # @param [String] dispute_id Required parameter: The ID of the dispute you
-    # want to submit evidence for.
+    # square/disputes-api/create-dispute-evidence-text) endpoints and
+    # evidence automatically provided by Square, when available.
+    # @param [String] dispute_id Required parameter: The ID of the dispute that
+    # you want to submit evidence for.
     # @return [SubmitEvidenceResponse Hash] response from the API call
     def submit_evidence(dispute_id:)
       # Prepare query url.

data/lib/square/api/invoices_api.rb

@@ -134,8 +134,8 @@ module Square
 
     # Deletes the specified invoice. When an invoice is deleted, the
     # associated Order status changes to CANCELED. You can only delete a draft
-    # invoice (you cannot delete an invoice scheduled for publication, or a
-    # published invoice).
+    # invoice (you cannot delete a published invoice, including one that is
+    # scheduled for processing).
     # @param [String] invoice_id Required parameter: The ID of the invoice to
     # delete.
     # @param [Integer] version Optional parameter: The version of the
@@ -214,12 +214,15 @@ module Square
       )
     end
 
-    # Updates an invoice by modifying field values, clearing field values, or
-    # both
-    # as specified in the request.
-    # There are no restrictions to updating an invoice in a draft state.
-    # However, there are guidelines for updating a published invoice.
-    # @param [String] invoice_id Required parameter: The id of the invoice to
+    # Updates an invoice by modifying fields, clearing fields, or both. For most
+    # updates, you can use a sparse
+    # `Invoice` object to add fields or change values, and use the
+    # `fields_to_clear` field to specify fields to clear.
+    # However, some restrictions apply. For example, you cannot change the
+    # `order_id` or `location_id` field, and you
+    # must provide the complete `custom_fields` list to update a custom field.
+    # Published invoices have additional restrictions.
+    # @param [String] invoice_id Required parameter: The ID of the invoice to
     # update.
     # @param [UpdateInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -261,8 +264,8 @@ module Square
 
     # Cancels an invoice. The seller cannot collect payments for
     # the canceled invoice.
-    # You cannot cancel an invoice in a terminal state: `PAID`, `REFUNDED`,
-    # `CANCELED`, or `FAILED`.
+    # You cannot cancel an invoice in the `DRAFT` state or in a terminal state:
+    # `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
     # @param [String] invoice_id Required parameter: The ID of the
     # [invoice](#type-invoice) to cancel.
     # @param [CancelInvoiceRequest] body Required parameter: An object

data/lib/square/api/payments_api.rb

@@ -83,16 +83,14 @@ module Square
       )
     end
 
-    # Charges a payment source (for example, a card
-    # represented by customer's card on file or a card nonce). In addition
-    # to the payment source, the request must include the
-    # amount to accept for the payment.
-    # There are several optional parameters that you can include in the request
-    # (for example, tip money, whether to autocomplete the payment, or a
-    # reference ID
-    # to correlate this payment with another system).
-    # The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required
-    # to enable application fees.
+    # Creates a payment using the provided source. You can use this endpoint
+    # to charge a card (credit/debit card or
+    # Square gift card) or record a payment that the seller received outside of
+    # Square
+    # (cash payment from a buyer or a payment that an external entity
+    # procesed on behalf of the seller).
+    # The endpoint creates a
+    # `Payment` object and returns it in the response.
     # @param [CreatePaymentRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -209,11 +207,53 @@ module Square
       )
     end
 
-    # Cancels (voids) a payment. If you set `autocomplete` to `false` when
-    # creating a payment,
-    # you can cancel the payment using this endpoint.
-    # @param [String] payment_id Required parameter: The `payment_id`
-    # identifying the payment to be canceled.
+    # Updates a payment with the APPROVED status.
+    # You can update the `amount_money` and `tip_money` using this endpoint.
+    # @param [String] payment_id Required parameter: The ID of the payment to
+    # update.
+    # @param [UpdatePaymentRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [UpdatePaymentResponse Hash] response from the API call
+    def update_payment(payment_id:,
+                       body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/payments/{payment_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'payment_id' => { 'value' => payment_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'content-type' => 'application/json; charset=utf-8'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.put(
+        _query_url,
+        headers: _headers,
+        parameters: body.to_json
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
+
+    # Cancels (voids) a payment. You can use this endpoint to cancel a payment
+    # with
+    # the APPROVED `status`.
+    # @param [String] payment_id Required parameter: The ID of the payment to
+    # cancel.
     # @return [CancelPaymentResponse Hash] response from the API call
     def cancel_payment(payment_id:)
       # Prepare query url.
@@ -249,9 +289,8 @@ module Square
     # Completes (captures) a payment.
     # By default, payments are set to complete immediately after they are
     # created.
-    # If you set `autocomplete` to `false` when creating a payment, you can
-    # complete (capture)
-    # the payment using this endpoint.
+    # You can use this endpoint to complete a payment with the APPROVED
+    # `status`.
     # @param [String] payment_id Required parameter: The unique ID identifying
     # the payment to be completed.
     # @return [CompletePaymentResponse Hash] response from the API call