Class: Square::V1TransactionsApi

Inherits:
BaseApi
  • Object
show all
Defined in:
lib/square/api/v1_transactions_api.rb

Overview

V1TransactionsApi

Instance Attribute Summary

Attributes inherited from BaseApi

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseApi

#execute_request, #get_user_agent, #validate_parameters

Constructor Details

#initialize(config, http_call_back: nil) ⇒ V1TransactionsApi

Returns a new instance of V1TransactionsApi.



4
5
6
 
# File 'lib/square/api/v1_transactions_api.rb', line 4

def initialize(config, http_call_back: nil)
  super(config, http_call_back: http_call_back)
end

Instance Method Details

#create_refund(location_id:, body:) ⇒ V1Refund Hash

Issues a refund for a previously processed payment. You must issue a refund within 60 days of the associated payment. You cannot issue a partial refund for a split tender payment. You must instead issue a full or partial refund for a particular tender, by providing the applicable tender id to the V1CreateRefund endpoint. Issuing a full refund for a split tender payment refunds all tenders associated with the payment. Issuing a refund for a card payment is not reversible. For development purposes, you can create fake cash payments in Square Point of Sale and refund them. payment's associated location. containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the original

  • body (V1CreateRefundRequest) —

    Required parameter: An object

Returns:

  • (V1Refund Hash) —

    response from the API call



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
 
# File 'lib/square/api/v1_transactions_api.rb', line 357

def create_refund(location_id:,
                  body:)
  warn 'Endpoint create_refund in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/refunds'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json',
    'Content-Type' => 'application/json'
  }

  # 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

#list_orders(location_id:, order: nil, limit: nil, batch_token: nil) ⇒ List of V1Order Hash

Provides summary information for a merchant's online store orders. list online store orders for. are listed in the response. to return in a single response. This value cannot exceed 200. retrieve the next set of results for your original query to the endpoint.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the location to

  • order (SortOrder) (defaults to: nil) —

    Optional parameter: The order in which payments

  • limit (Integer) (defaults to: nil) —

    Optional parameter: The maximum number of payments

  • batch_token (String) (defaults to: nil) —

    Optional parameter: A pagination cursor to

Returns:

  • (List of V1Order Hash) —

    response from the API call



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/square/api/v1_transactions_api.rb', line 19

def list_orders(location_id:,
                order: nil,
                limit: nil,
                batch_token: nil)
  warn 'Endpoint list_orders in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/orders'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true }
  )
  _query_builder = APIHelper.append_url_with_query_parameters(
    _query_builder,
    'order' => order,
    'limit' => limit,
    'batch_token' => batch_token
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  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

#list_payments(location_id:, order: nil, begin_time: nil, end_time: nil, limit: nil, batch_token: nil, include_partial: false) ⇒ List of V1Payment Hash

Provides summary information for all payments taken for a given Square account during a date range. Date ranges cannot exceed 1 year in length. See Date ranges for details of inclusive and exclusive dates. Note*: Details for payments processed with Square Point of Sale while in offline mode may not be transmitted to Square for up to 72 hours. Offline payments have a `created_at` value that reflects the time the payment was originally processed, not the time it was subsequently transmitted to Square. Consequently, the ListPayments endpoint might list an offline payment chronologically between online payments that were seen in a previous request. list payments for. If you specify me, this endpoint returns payments aggregated from all of the business's locations. are listed in the response. requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. to return in a single response. This value cannot exceed 200. retrieve the next set of results for your original query to the endpoint. not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the location to

  • order (SortOrder) (defaults to: nil) —

    Optional parameter: The order in which payments

  • begin_time (String) (defaults to: nil) —

    Optional parameter: The beginning of the

  • end_time (String) (defaults to: nil) —

    Optional parameter: The end of the requested

  • limit (Integer) (defaults to: nil) —

    Optional parameter: The maximum number of payments

  • batch_token (String) (defaults to: nil) —

    Optional parameter: A pagination cursor to

  • include_partial (Boolean) (defaults to: false) —

    Optional parameter: Indicates whether or

Returns:

  • (List of V1Payment Hash) —

    response from the API call



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/square/api/v1_transactions_api.rb', line 183

def list_payments(location_id:,
                  order: nil,
                  begin_time: nil,
                  end_time: nil,
                  limit: nil,
                  batch_token: nil,
                  include_partial: false)
  warn 'Endpoint list_payments in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/payments'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true }
  )
  _query_builder = APIHelper.append_url_with_query_parameters(
    _query_builder,
    'order' => order,
    'begin_time' => begin_time,
    'end_time' => end_time,
    'limit' => limit,
    'batch_token' => batch_token,
    'include_partial' => include_partial
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  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

#list_refunds(location_id:, order: nil, begin_time: nil, end_time: nil, limit: nil, batch_token: nil) ⇒ List of V1Refund Hash

Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. list refunds for. are listed in the response. requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. retrieve the next set of results for your original query to the endpoint.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the location to

  • order (SortOrder) (defaults to: nil) —

    Optional parameter: The order in which payments

  • begin_time (String) (defaults to: nil) —

    Optional parameter: The beginning of the

  • end_time (String) (defaults to: nil) —

    Optional parameter: The end of the requested

  • limit (Integer) (defaults to: nil) —

    Optional parameter: The approximate number of

  • batch_token (String) (defaults to: nil) —

    Optional parameter: A pagination cursor to

Returns:

  • (List of V1Refund Hash) —

    response from the API call



296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 
# File 'lib/square/api/v1_transactions_api.rb', line 296

def list_refunds(location_id:,
                 order: nil,
                 begin_time: nil,
                 end_time: nil,
                 limit: nil,
                 batch_token: nil)
  warn 'Endpoint list_refunds in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/refunds'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true }
  )
  _query_builder = APIHelper.append_url_with_query_parameters(
    _query_builder,
    'order' => order,
    'begin_time' => begin_time,
    'end_time' => end_time,
    'limit' => limit,
    'batch_token' => batch_token
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  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

#list_settlements(location_id:, order: nil, begin_time: nil, end_time: nil, limit: nil, status: nil, batch_token: nil) ⇒ List of V1Settlement Hash

Provides summary information for all deposits and withdrawals initiated by Square to a linked bank account during a date range. Date ranges cannot exceed one year in length. Note*: the ListSettlements endpoint does not provide entry information. list settlements for. If you specify me, this endpoint returns settlements aggregated from all of the business's locations. settlements are listed in the response. requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. settlements to return in a single response. This value cannot exceed 200. this parameter to retrieve only settlements with a particular status (SENT or FAILED). retrieve the next set of results for your original query to the endpoint.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the location to

  • order (SortOrder) (defaults to: nil) —

    Optional parameter: The order in which

  • begin_time (String) (defaults to: nil) —

    Optional parameter: The beginning of the

  • end_time (String) (defaults to: nil) —

    Optional parameter: The end of the requested

  • limit (Integer) (defaults to: nil) —

    Optional parameter: The maximum number of

  • status (V1ListSettlementsRequestStatus) (defaults to: nil) —

    Optional parameter: Provide

  • batch_token (String) (defaults to: nil) —

    Optional parameter: A pagination cursor to

Returns:

  • (List of V1Settlement Hash) —

    response from the API call



420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'lib/square/api/v1_transactions_api.rb', line 420

def list_settlements(location_id:,
                     order: nil,
                     begin_time: nil,
                     end_time: nil,
                     limit: nil,
                     status: nil,
                     batch_token: nil)
  warn 'Endpoint list_settlements in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/settlements'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true }
  )
  _query_builder = APIHelper.append_url_with_query_parameters(
    _query_builder,
    'order' => order,
    'begin_time' => begin_time,
    'end_time' => end_time,
    'limit' => limit,
    'status' => status,
    'batch_token' => batch_token
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  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

#retrieve_order(location_id:, order_id:) ⇒ V1Order Hash

Provides comprehensive information for a single online store order, including the order's history. associated location. You obtain this value from Order objects returned by the List Orders endpoint

Parameters:

  • location_id (String) —

    Required parameter: The ID of the order's

  • order_id (String) —

    Required parameter: The order's Square-issued ID.

Returns:

  • (V1Order Hash) —

    response from the API call



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/square/api/v1_transactions_api.rb', line 68

def retrieve_order(location_id:,
                   order_id:)
  warn 'Endpoint retrieve_order in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/orders/{order_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true },
    'order_id' => { 'value' => order_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  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

#retrieve_payment(location_id:, payment_id:) ⇒ V1Payment Hash

Provides comprehensive information for a single payment. associated location. ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the payment's

  • payment_id (String) —

    Required parameter: The Square-issued payment

Returns:

  • (V1Payment Hash) —

    response from the API call



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/square/api/v1_transactions_api.rb', line 238

def retrieve_payment(location_id:,
                     payment_id:)
  warn 'Endpoint retrieve_payment in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/payments/{payment_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true },
    'payment_id' => { 'value' => payment_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  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

#retrieve_settlement(location_id:, settlement_id:) ⇒ V1Settlement Hash

Provides comprehensive information for a single settlement. The returned `Settlement` objects include an `entries` field that lists the transactions that contribute to the settlement total. Most settlement entries correspond to a payment payout, but settlement entries are also generated for less common events, like refunds, manual adjustments, or chargeback holds. Square initiates its regular deposits as indicated in the [Deposit Options with Square](squareup.com/help/us/en/article/3807) help article. Details for a regular deposit are usually not available from Connect API endpoints before 10 p.m. PST the same day. Square does not know when an initiated settlement *completes*, only whether it has failed. A completed settlement is typically reflected in a bank account within 3 business days, but in exceptional cases it may take longer. settlements's associated location. Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the

  • settlement_id (String) —

    Required parameter: The settlement's

Returns:

  • (V1Settlement Hash) —

    response from the API call



488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
 
# File 'lib/square/api/v1_transactions_api.rb', line 488

def retrieve_settlement(location_id:,
                        settlement_id:)
  warn 'Endpoint retrieve_settlement in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/settlements/{settlement_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true },
    'settlement_id' => { 'value' => settlement_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  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

#update_order(location_id:, order_id:, body:) ⇒ V1Order Hash

Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions: associated location. You obtain this value from Order objects returned by the List Orders endpoint containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • location_id (String) —

    Required parameter: The ID of the order's

  • order_id (String) —

    Required parameter: The order's Square-issued ID.

  • body (V1UpdateOrderRequest) —

    Required parameter: An object

Returns:

  • (V1Order Hash) —

    response from the API call



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/square/api/v1_transactions_api.rb', line 113

def update_order(location_id:,
                 order_id:,
                 body:)
  warn 'Endpoint update_order in V1TransactionsApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v1/{location_id}/orders/{order_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'location_id' => { 'value' => location_id, 'encode' => true },
    'order_id' => { 'value' => order_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json',
    'Content-Type' => 'application/json'
  }

  # 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