diff --git a/CHANGELOG.md b/CHANGELOG.md index 849327d4..96c6d57b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,53 @@ # Change Log +## Version 15.0.0.20211020 (2021-10-20) +## API updates +* **Transactions API.** Three previously deprecated endpoints (`ListRefunds`, `Charge`, and `CreateRefund`) in the [Transactions API](https://developer.squareup.com/reference/square_2021-10-20/transactions-api) are removed from Square API version 2021-10-20 and later. These endpoints will work if you are using Square API versions prior to 2021-10-20. However, these endpoints will eventually be retired from all Square versions. + + * Instead of the Transactions API `Charge` endpoint, use the Payments API [CreatePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment) endpoint. + * Instead of the Transactions API `CreateRefund` endpoint, use the Refunds API [RefundPayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/refund-payment) endpoint. + * Instead of the Transactions API `ListRefunds` endpoint, use the Refunds API [ListPaymentRefund](https://developer.squareup.com/reference/square_2021-10-20/payments-api/list-payment-refunds) endpoint. + +* **Payments API:** + * [Payment](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment) object. + * Added the [device_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-device_details) read-only field to view details of the device used to take a payment. This `Payment`-level field provides device information for all types of payments. Previously, device details were only available for card payments (`Payment.card_details.device_details`), which is now deprecated. + * Added the [team_member_id](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-team_member_id) that applications can use to view the ID of the [TeamMember](https://developer.squareup.com/reference/square_2021-10-20/objects/TeamMember) associated with the payment. Use this field instead of the `Payment.employee_id` field, which is now deprecated. + * Added the [application_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-application_details) read-only field to view details of the application that took the payment. + + * These `Payment` fields have moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle) (GA) state:[tip_money](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-tip_money), [delay_duration](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_duration), [statement_description_identifier](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-statement_description_identifier), [delay_duration](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_duration), [delay_action](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_action), [delayed_until](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delayed_until), and [statement_description_identifier](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-statement_description_identifier). + + * The [ACH Bank Transfer Payments](https://developer.squareup.com/docs/payments-api/take-payments/ach-payments) feature has moved to the GA state. Accordingly, the [bank_account_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-bank_account_details) field (and its [BankAccountPaymentDetails](https://developer.squareup.com/reference/square_2021-10-20/objects/BankAccountPaymentDetails) type) are moved to the GA state. + * [CreatePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment) endpoint. + * Added the [team_member_id](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment#request__property-team_member_id) request field to record the ID of the team member associated with the payment. + * The [accept_partial_authorization](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment#request__property-accept_partial_authorization) request field has moved to the GA state. + * [CompletePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/complete-payment) endpoint. Added the `version_token` request field to support optimistic concurrency. For more information, see [Delayed capture of a card payment.](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment) + +* **Refunds API:** + * [RefundPayment](https://developer.squareup.com/reference/square_2021-10-20/refunds-api/refund-payment) endpoint. + * Added the `team_member_id` request field to record the ID of the team member associated with the refund. + * Added the `payment_version_token` request field to support optimistic concurrency. For more information, see [Refund Payment.](https://developer.squareup.com/docs/payments-api/refund-payments#optimistic-concurrency) + +* **Customers API:** + * [Customer](https://developer.squareup.com/reference/square_2021-10-20/objects/Customer) object. Added a new `tax_ids` field of the [CustomerTaxIds](https://developer.squareup.com/reference/square_2021-10-20/objects/CustomerTaxIds) type, which can contain the EU VAT ID of the customer. This field is available only for customers of sellers in France, Ireland, or the United Kingdom. For more information, see [Customer tax IDs.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids) + + * [UpdateCustomer](https://developer.squareup.com/reference/square_2021-10-20/customers-api/update-customer) endpoint. The Customers API now returns a `400 BAD_REQUEST` error if the request body does not contain any fields. For earlier Square versions, the Customers API will continue to return a `200 OK` response along with the customer profile. For more information, see [Migration notes.](https://developer.squareup.com/docs/customers-api/what-it-does#migration-notes) + +* **Invoices API:** + * [InvoiceRecipient](https://developer.squareup.com/reference/square_2021-10-20/objects/InvoiceRecipient) object. Added a new, read-only `tax_ids` field of the [InvoiceRecipientTaxIds](https://developer.squareup.com/reference/square_2021-10-20/objects/InvoiceRecipientTaxIds) type, which can contain the EU VAT ID of the invoice recipient. This field is available only for customers of sellers in Ireland or the United Kingdom. If defined, `tax_ids` is returned for all Square API versions. For more information, see [Invoice recipient tax IDs.](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids) + * Square now sends emails for test invoices that are published in the Sandbox environment. + +* **Catalog API:** + * [CatalogSubscriptionPlan.name](https://developer.squareup.com/reference/square_2021-10-20/objects/CatalogSubscriptionPlan#definition__property-name) can be updated after the subscription plan is created. The change is retroactively applicable to prior versions of the Square API. + +* **Subscriptions API:** + * The new [SubscriptionSource](https://developer.squareup.com/reference/square_2021-10-20/objects/SubscriptionSource) data type is introduced to encapsulate the source where a subscription is created. The new `SubscriptionSource.name` value is propagated to the `Order.source` attribute when an order is made on the subscription. The new feature is retroactively applicable to prior versions of the Square API. + * The new [Subscription.source](https://developer.squareup.com/reference/square_2021-10-20/objects/Subscription#definition__property-source) attribute is introduced to indicate the source where the subscription was created. This new feature is retroactively applicable to prior versions of the Square API. + * The new [SearchSubscriptionsFilter.source_names](https://developer.squareup.com/reference/square_2021-10-20/objects/SearchSubscriptionFilter#definition__property-source_names) query expression is introduced to enable search for subscriptions by the subscription source name. This new feature is retroactively applicable to prior versions of the Square API. + + ## Version 14.1.1.20210915 (2021-09-15) ## SDK updates -* Upgraded josnpickle dependency +* Upgraded jsonpickle dependency ## Version 14.1.0.20210915 (2021-09-15) ## API updates diff --git a/doc/api/payments.md b/doc/api/payments.md index 79c2a03e..2d57c173 100644 --- a/doc/api/payments.md +++ b/doc/api/payments.md @@ -111,10 +111,10 @@ def create_payment(self, ```python body = {} -body['source_id'] = 'ccof:uIbfJXhXETSP197M3GB' -body['idempotency_key'] = '4935a656-a929-4792-b97c-8848be85c27c' +body['source_id'] = 'ccof:GaJGNaZa8x4OgDJn4GB' +body['idempotency_key'] = '7b0f3ec5-086a-4871-8f13-3c81b3875218' body['amount_money'] = {} -body['amount_money']['amount'] = 200 +body['amount_money']['amount'] = 1000 body['amount_money']['currency'] = 'USD' body['tip_money'] = {} body['tip_money']['amount'] = 198 @@ -125,8 +125,8 @@ body['app_fee_money']['currency'] = 'USD' body['delay_duration'] = 'delay_duration6' body['autocomplete'] = True body['order_id'] = 'order_id0' -body['customer_id'] = 'VDKXEEKPJN48QDG3BGGFAK05P8' -body['location_id'] = 'XK3DBG77NJBFX' +body['customer_id'] = 'W92WH6P11H4Z77CTET0RNTGFW8' +body['location_id'] = 'L88917AVBK2S5' body['reference_id'] = '123456' body['note'] = 'Brief description' @@ -251,10 +251,10 @@ body['payment']['amount_money'] = {} body['payment']['amount_money']['amount'] = 1000 body['payment']['amount_money']['currency'] = 'USD' body['payment']['tip_money'] = {} -body['payment']['tip_money']['amount'] = 300 +body['payment']['tip_money']['amount'] = 100 body['payment']['tip_money']['currency'] = 'USD' -body['payment']['version_token'] = 'Z3okDzm2VRv5m5nE3WGx381ItTNhvjkB4VapByyz54h6o' -body['idempotency_key'] = '3d3c3b22-9572-4fc6-1111-e4d2f41b4122' +body['payment']['version_token'] = 'ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o' +body['idempotency_key'] = '956f8b13-e4ec-45d6-85e8-d1d95ef0c5de' result = payments_api.update_payment(payment_id, body) @@ -308,7 +308,8 @@ You can use this endpoint to complete a payment with the APPROVED `status`. ```python def complete_payment(self, - payment_id) + payment_id, + body) ``` ## Parameters @@ -316,6 +317,7 @@ def complete_payment(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `payment_id` | `string` | Template, Required | The unique ID identifying the payment to be completed. | +| `body` | [`Complete Payment Request`](/doc/models/complete-payment-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | ## Response Type @@ -325,8 +327,10 @@ def complete_payment(self, ```python payment_id = 'payment_id0' +body = {} +body['version_token'] = 'version_token2' -result = payments_api.complete_payment(payment_id) +result = payments_api.complete_payment(payment_id, body) if result.is_success(): print(result.body) diff --git a/doc/api/refunds.md b/doc/api/refunds.md index 10fda6f3..79bb9ca5 100644 --- a/doc/api/refunds.md +++ b/doc/api/refunds.md @@ -100,15 +100,17 @@ def refund_payment(self, ```python body = {} -body['idempotency_key'] = 'a7e36d40-d24b-11e8-b568-0800200c9a66' +body['idempotency_key'] = '9b7f2dcf-49da-4411-b23e-a2d6af21333a' body['amount_money'] = {} -body['amount_money']['amount'] = 100 +body['amount_money']['amount'] = 1000 body['amount_money']['currency'] = 'USD' body['app_fee_money'] = {} -body['app_fee_money']['amount'] = 114 -body['app_fee_money']['currency'] = 'GEL' -body['payment_id'] = 'UNOE3kv2BZwqHlJ830RCt5YCuaB' -body['reason'] = 'reason8' +body['app_fee_money']['amount'] = 10 +body['app_fee_money']['currency'] = 'USD' +body['payment_id'] = 'R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY' +body['reason'] = 'Example' +body['payment_version_token'] = 'payment_version_token6' +body['team_member_id'] = 'team_member_id4' result = refunds_api.refund_payment(body) diff --git a/doc/api/subscriptions.md b/doc/api/subscriptions.md index 7085562e..83f6adff 100644 --- a/doc/api/subscriptions.md +++ b/doc/api/subscriptions.md @@ -51,7 +51,7 @@ body['idempotency_key'] = '8193148c-9586-11e6-99f9-28cfe92138cf' body['location_id'] = 'S8GWD5R9QB376' body['plan_id'] = '6JHXF3B2CW3YKHDV4XEM674H' body['customer_id'] = 'CHFGVKYY8RSV93M5KCYTG4PN0G' -body['start_date'] = '2020-08-01' +body['start_date'] = '2021-10-20' body['canceled_date'] = 'canceled_date0' body['tax_percentage'] = '5' body['price_override_money'] = {} @@ -59,6 +59,8 @@ body['price_override_money']['amount'] = 100 body['price_override_money']['currency'] = 'USD' body['card_id'] = 'ccof:qy5x8hHGYsgLrp4Q4GB' body['timezone'] = 'America/Los_Angeles' +body['source'] = {} +body['source']['name'] = 'My App' result = subscriptions_api.create_subscription(body) @@ -113,6 +115,7 @@ body['query'] = {} body['query']['filter'] = {} body['query']['filter']['customer_ids'] = ['CHFGVKYY8RSV93M5KCYTG4PN0G'] body['query']['filter']['location_ids'] = ['S8GWD5R9QB376'] +body['query']['filter']['source_names'] = ['My App'] result = subscriptions_api.search_subscriptions(body) diff --git a/doc/api/transactions.md b/doc/api/transactions.md index 65212168..48fb2e16 100644 --- a/doc/api/transactions.md +++ b/doc/api/transactions.md @@ -10,71 +10,12 @@ transactions_api = client.transactions ## Methods -* [List Refunds](/doc/api/transactions.md#list-refunds) * [List Transactions](/doc/api/transactions.md#list-transactions) -* [Charge](/doc/api/transactions.md#charge) * [Retrieve Transaction](/doc/api/transactions.md#retrieve-transaction) * [Capture Transaction](/doc/api/transactions.md#capture-transaction) -* [Create Refund](/doc/api/transactions.md#create-refund) * [Void Transaction](/doc/api/transactions.md#void-transaction) -# List Refunds - -**This endpoint is deprecated.** - -Lists refunds for one of a business's locations. - -In addition to full or partial tender refunds processed through Square APIs, -refunds may result from itemized returns or exchanges through Square's -Point of Sale applications. - -Refunds with a `status` of `PENDING` are not currently included in this -endpoint's response. - -Max results per [page](https://developer.squareup.com/docs/working-with-apis/pagination): 50 - -```python -def list_refunds(self, - location_id, - begin_time=None, - end_time=None, - sort_order=None, - cursor=None) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `string` | Template, Required | The ID of the location to list refunds for. | -| `begin_time` | `string` | Query, Optional | The beginning of the requested reporting period, in RFC 3339 format.

See [Date ranges](https://developer.squareup.com/docs/build-basics/working-with-dates) for details on date inclusivity/exclusivity.

Default value: The current time minus one year. | -| `end_time` | `string` | Query, Optional | The end of the requested reporting period, in RFC 3339 format.

See [Date ranges](https://developer.squareup.com/docs/build-basics/working-with-dates) for details on date inclusivity/exclusivity.

Default value: The current time. | -| `sort_order` | [`str (Sort Order)`](/doc/models/sort-order.md) | Query, Optional | The order in which results are listed in the response (`ASC` for
oldest first, `DESC` for newest first).

Default value: `DESC` | -| `cursor` | `string` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for your original query.

See [Paginating results](https://developer.squareup.com/docs/working-with-apis/pagination) for more information. | - -## Response Type - -[`List Refunds Response`](/doc/models/list-refunds-response.md) - -## Example Usage - -```python -location_id = 'location_id4' -begin_time = 'begin_time2' -end_time = 'end_time2' -sort_order = 'DESC' -cursor = 'cursor6' - -result = transactions_api.list_refunds(location_id, begin_time, end_time, sort_order, cursor) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - # List Transactions **This endpoint is deprecated.** @@ -127,99 +68,6 @@ elif result.is_error(): ``` -# Charge - -**This endpoint is deprecated.** - -Charges a card represented by a card nonce or a customer's card on file. - -Your request to this endpoint must include _either_: - -- A value for the `card_nonce` parameter (to charge a card payment token generated - with the Web Payments SDK) -- Values for the `customer_card_id` and `customer_id` parameters (to charge - a customer's card on file) - -In order for an eCommerce payment to potentially qualify for -[Square chargeback protection](https://squareup.com/help/article/5394), you -_must_ provide values for the following parameters in your request: - -- `buyer_email_address` -- At least one of `billing_address` or `shipping_address` - -When this response is returned, the amount of Square's processing fee might not yet be -calculated. To obtain the processing fee, wait about ten seconds and call -[RetrieveTransaction](/doc/api/transactions.md#retrieve-transaction). See the `processing_fee_money` -field of each [Tender included](/doc/models/tender.md) in the transaction. - -```python -def charge(self, - location_id, - body) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `string` | Template, Required | The ID of the location to associate the created transaction with. | -| `body` | [`Charge Request`](/doc/models/charge-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -## Response Type - -[`Charge Response`](/doc/models/charge-response.md) - -## Example Usage - -```python -location_id = 'location_id4' -body = {} -body['idempotency_key'] = '74ae1696-b1e3-4328-af6d-f1e04d947a13' -body['amount_money'] = {} -body['amount_money']['amount'] = 200 -body['amount_money']['currency'] = 'USD' -body['card_nonce'] = 'card_nonce_from_square_123' -body['customer_card_id'] = 'customer_card_id6' -body['delay_capture'] = False -body['reference_id'] = 'some optional reference id' -body['note'] = 'some optional note' -body['billing_address'] = {} -body['billing_address']['address_line_1'] = '500 Electric Ave' -body['billing_address']['address_line_2'] = 'Suite 600' -body['billing_address']['address_line_3'] = 'address_line_38' -body['billing_address']['locality'] = 'New York' -body['billing_address']['sublocality'] = 'sublocality2' -body['billing_address']['administrative_district_level_1'] = 'NY' -body['billing_address']['postal_code'] = '10003' -body['billing_address']['country'] = 'US' -body['shipping_address'] = {} -body['shipping_address']['address_line_1'] = '123 Main St' -body['shipping_address']['address_line_2'] = 'address_line_24' -body['shipping_address']['address_line_3'] = 'address_line_30' -body['shipping_address']['locality'] = 'San Francisco' -body['shipping_address']['sublocality'] = 'sublocality4' -body['shipping_address']['administrative_district_level_1'] = 'CA' -body['shipping_address']['postal_code'] = '94114' -body['shipping_address']['country'] = 'US' -body['additional_recipients'] = [] - -body['additional_recipients'].append({}) -body['additional_recipients'][0]['location_id'] = '057P5VYJ4A5X1' -body['additional_recipients'][0]['description'] = 'Application fees' -body['additional_recipients'][0]['amount_money'] = {} -body['additional_recipients'][0]['amount_money']['amount'] = 20 -body['additional_recipients'][0]['amount_money']['currency'] = 'USD' - - -result = transactions_api.charge(location_id, body) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - # Retrieve Transaction **This endpoint is deprecated.** @@ -262,7 +110,7 @@ elif result.is_error(): **This endpoint is deprecated.** -Captures a transaction that was created with the [Charge](/doc/api/transactions.md#charge) +Captures a transaction that was created with the [Charge]($e/Transactions/Charge) endpoint with a `delay_capture` value of `true`. See [Delayed capture transactions](https://developer.squareup.com/docs/payments/transactions/overview#delayed-capture) @@ -300,66 +148,11 @@ elif result.is_error(): ``` -# Create Refund - -**This endpoint is deprecated.** - -Initiates a refund for a previously charged tender. - -You must issue a refund within 120 days of the associated payment. See -[this article](https://squareup.com/help/us/en/article/5060) for more information -on refund behavior. - -NOTE: Card-present transactions with Interac credit cards **cannot be -refunded using the Connect API**. Interac transactions must refunded -in-person (e.g., dipping the card using POS app). - -```python -def create_refund(self, - location_id, - transaction_id, - body) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `string` | Template, Required | The ID of the original transaction's associated location. | -| `transaction_id` | `string` | Template, Required | The ID of the original transaction that includes the tender to refund. | -| `body` | [`Create Refund Request`](/doc/models/create-refund-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -## Response Type - -[`Create Refund Response`](/doc/models/create-refund-response.md) - -## Example Usage - -```python -location_id = 'location_id4' -transaction_id = 'transaction_id8' -body = {} -body['idempotency_key'] = '86ae1696-b1e3-4328-af6d-f1e04d947ad2' -body['tender_id'] = 'MtZRYYdDrYNQbOvV7nbuBvMF' -body['reason'] = 'a reason' -body['amount_money'] = {} -body['amount_money']['amount'] = 100 -body['amount_money']['currency'] = 'USD' - -result = transactions_api.create_refund(location_id, transaction_id, body) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - # Void Transaction **This endpoint is deprecated.** -Cancels a transaction that was created with the [Charge](/doc/api/transactions.md#charge) +Cancels a transaction that was created with the [Charge]($e/Transactions/Charge) endpoint with a `delay_capture` value of `true`. See [Delayed capture transactions](https://developer.squareup.com/docs/payments/transactions/overview#delayed-capture) diff --git a/doc/client.md b/doc/client.md index c25d5ff9..8ba641b0 100644 --- a/doc/client.md +++ b/doc/client.md @@ -5,7 +5,7 @@ The following parameters are configurable for the API Client: | Parameter | Type | Description | | --- | --- | --- | -| `square_version` | `string` | Square Connect API versions
*Default*: `'2021-09-15'` | +| `square_version` | `string` | Square Connect API versions
*Default*: `'2021-10-20'` | | `access_token` | `string` | The OAuth 2.0 Access Token to use for API requests. | | `custom_url` | `string` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
*Default*: `'https://connect.squareup.com'` | | `environment` | `string` | The API environment.
**Default: `production`** | @@ -22,7 +22,7 @@ The API client can be initialized as follows: from square.client import Client client = Client( - square_version='2021-09-15', + square_version='2021-10-20', access_token='AccessToken', environment='production', custom_url = 'https://connect.squareup.com',) @@ -47,7 +47,7 @@ API calls return an `ApiResponse` object that includes the following fields: from square.client import Client client = Client( - square_version='2021-09-15', + square_version='2021-10-20', access_token='AccessToken',) locations_api = client.locations diff --git a/doc/models/application-details-external-square-product.md b/doc/models/application-details-external-square-product.md new file mode 100644 index 00000000..2422f67f --- /dev/null +++ b/doc/models/application-details-external-square-product.md @@ -0,0 +1,24 @@ + +# Application Details External Square Product + +A list of products to return to external callers. + +## Enumeration + +`Application Details External Square Product` + +## Fields + +| Name | +| --- | +| `APPOINTMENTS` | +| `ECOMMERCE_API` | +| `INVOICES` | +| `ONLINE_STORE` | +| `OTHER` | +| `RESTAURANTS` | +| `RETAIL` | +| `SQUARE_POS` | +| `TERMINAL_API` | +| `VIRTUAL_TERMINAL` | + diff --git a/doc/models/application-details.md b/doc/models/application-details.md new file mode 100644 index 00000000..5e8b71fc --- /dev/null +++ b/doc/models/application-details.md @@ -0,0 +1,25 @@ + +# Application Details + +Details about the application that took the payment. + +## Structure + +`Application Details` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `square_product` | [`str (Application Details External Square Product)`](/doc/models/application-details-external-square-product.md) | Optional | A list of products to return to external callers. | +| `application_id` | `string` | Optional | The Square ID assigned to the application used to take the payment.
Application developers can use this information to identify payments that
their application processed.
For example, if a developer uses a custom application to process payments,
this field contains the application ID from the Developer Dashboard.
If a seller uses a [Square App Marketplace](https://developer.squareup.com/docs/app-marketplace)
application to process payments, the field contains the corresponding application ID. | + +## Example (as JSON) + +```json +{ + "square_product": "TERMINAL_API", + "application_id": "application_id4" +} +``` + diff --git a/doc/models/cancel-payment-response.md b/doc/models/cancel-payment-response.md index cb069e3d..8e8e78aa 100644 --- a/doc/models/cancel-payment-response.md +++ b/doc/models/cancel-payment-response.md @@ -20,54 +20,64 @@ Defines the response returned by [CancelPayment](/doc/api/payments.md#cancel-pay { "payment": { "amount_money": { - "amount": 200, + "amount": 1000, "currency": "USD" }, - "app_fee_money": { - "amount": 10, - "currency": "USD" + "application_details": { + "application_id": "sq0ids-TcgftTEtKxJTRF1lCFJ9TA", + "square_product": "ECOMMERCE_API" }, "approved_money": { - "amount": 200, + "amount": 1000, "currency": "USD" }, "card_details": { - "auth_result_code": "eWZBDh", + "auth_result_code": "68aLBM", "avs_status": "AVS_ACCEPTED", "card": { "bin": "411111", "card_brand": "VISA", "card_type": "DEBIT", - "exp_month": 2, - "exp_year": 2024, - "fingerprint": "sq-1-9PP0tWfcM6vIsYmfsesdjfhduHSDFNdJFNDfDNFjdfjpseirDErsaP", - "last_4": "1234", - "prepaid_type": "PREPAID" + "exp_month": 11, + "exp_year": 2022, + "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ", + "last_4": "1111", + "prepaid_type": "NOT_PREPAID" }, "card_payment_timeline": { - "authorized_at": "2018-10-17T20:38:46.753Z", - "voided_at": "2018-10-17T20:38:57.793Z" + "authorized_at": "2021-10-13T20:26:44.364Z", + "voided_at": "2021-10-13T20:31:21.597Z" }, "cvv_status": "CVV_ACCEPTED", - "entry_method": "KEYED", - "statement_description": "SQ *MY MERCHANT", + "entry_method": "ON_FILE", + "statement_description": "SQ *EXAMPLE TEST GOSQ.C", "status": "VOIDED" }, - "created_at": "2018-10-17T20:38:46.743Z", - "customer_id": "RDX9Z4XTIZR7MRZJUXNY9HUK6I", - "id": "GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", - "location_id": "XTI0H92143A39", - "note": "Brief description", - "order_id": "m2Hr8Hk8A3CTyQQ1k4ynExg92tO3", - "reference_id": "123456", + "created_at": "2021-10-13T20:26:44.191Z", + "customer_id": "W92WH6P11H4Z77CTET0RNTGFW8", + "delay_action": "CANCEL", + "delay_duration": "PT168H", + "delayed_until": "2021-10-20T20:26:44.191Z", + "id": "1QjqpBVyrI9S4H9sTGDWU9JeiWdZY", + "location_id": "L88917AVBK2S5", + "note": "Example Note", + "order_id": "nUSN9TdxpiK3SrQg3wzmf6r8LP9YY", + "risk_evaluation": { + "created_at": "2021-10-13T20:26:45.271Z", + "risk_level": "NORMAL" + }, "source_type": "CARD", "status": "CANCELED", + "tip_money": { + "amount": 100, + "currency": "USD" + }, "total_money": { - "amount": 200, + "amount": 1100, "currency": "USD" }, - "updated_at": "2018-10-17T20:38:57.693Z", - "version_token": "lAITJ6l8I8tFu62mCf2W4sxJQxN9FOaH5zwfsdPf7Dm6o" + "updated_at": "2021-10-13T20:31:21.597Z", + "version_token": "N8AGYgEjCiY9Q57Jw7aVHEpBq8bzGCDCQMRX8Vs56N06o" } } ``` diff --git a/doc/models/cancel-subscription-response.md b/doc/models/cancel-subscription-response.md index 37ba4bfe..f5df7256 100644 --- a/doc/models/cancel-subscription-response.md +++ b/doc/models/cancel-subscription-response.md @@ -20,15 +20,18 @@ Defines fields that are included in a ```json { "subscription": { - "canceled_date": "2020-05-01", + "canceled_date": "2021-10-20", "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB", - "created_at": "2020-08-03T21:53:10Z", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "910afd30-464a-4e00-a8d8-2296eEXAMPLE", "location_id": "S8GWD5R9QB376", - "paid_until_date": "2020-05-01", + "paid_until_date": "2021-11-20", "plan_id": "6JHXF3B2CW3YKHDV4XEM674H", - "start_date": "2020-04-24", + "source": { + "name": "My App" + }, + "start_date": "2021-10-20", "status": "ACTIVE", "timezone": "America/Los_Angeles", "version": 1594311617331 diff --git a/doc/models/card.md b/doc/models/card.md index 7684bc5a..4c50dd8f 100644 --- a/doc/models/card.md +++ b/doc/models/card.md @@ -19,7 +19,7 @@ details are determined by the payment token generated by Web Payments SDK. | `exp_year` | `long\|int` | Optional | The four-digit year of the card's expiration date. | | `cardholder_name` | `string` | Optional | The name of the cardholder.
**Constraints**: *Maximum Length*: `96` | | `billing_address` | [`Address`](/doc/models/address.md) | Optional | Represents a postal address in a country. The address format is based
on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
`Address` object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.

For the remaining address components, the `Address` type provides the
`address_line_1` and `address_line_2` fields for free-form data entry.
These fields are free-form because the remaining address components have
too many variations around the world and typical software does not parse
these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other `Address` type fields are blank.
These include `address_line_3`, `sublocality_2`, `sublocality_3`,
`administrative_district_level_2`, `administrative_district_level_3`,
`first_name`, `last_name`, and `organization`.

When it comes to localization, the seller's language preferences
(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
are ignored for addresses. Even though Square products (such as Square Point of Sale
and the Seller Dashboard) mostly use a seller's language preference in
communication, when it comes to addresses, they will use English for a US address,
Japanese for an address in Japan, and so on. | -| `fingerprint` | `string` | Optional | __Not currently set.__ Intended as a Square-assigned identifier, based
on the card number, to identify the card across multiple locations within a
single application.
**Constraints**: *Maximum Length*: `255` | +| `fingerprint` | `string` | Optional | Intended as a Square-assigned identifier, based
on the card number, to identify the card across multiple locations within a
single application.
**Constraints**: *Maximum Length*: `255` | | `customer_id` | `string` | Optional | The ID of a customer created using the Customers API to be associated with the card. | | `reference_id` | `string` | Optional | An optional user-defined reference ID that associates this card with
another entity in an external system. For example, a customer ID from an
external customer management system.
**Constraints**: *Maximum Length*: `128` | | `enabled` | `bool` | Optional | Indicates whether or not a card can be used for payments. | diff --git a/doc/models/charge-request.md b/doc/models/charge-request.md index b6043e08..688f03e8 100644 --- a/doc/models/charge-request.md +++ b/doc/models/charge-request.md @@ -2,7 +2,7 @@ # Charge Request Defines the parameters that can be included in the body of -a request to the [Charge](/doc/api/transactions.md#charge) endpoint. +a request to the [Charge]($e/Transactions/Charge) endpoint. Deprecated - recommend using [CreatePayment](/doc/api/payments.md#create-payment) diff --git a/doc/models/charge-response.md b/doc/models/charge-response.md index 7c0be606..f09ed3f6 100644 --- a/doc/models/charge-response.md +++ b/doc/models/charge-response.md @@ -2,7 +2,7 @@ # Charge Response Defines the fields that are included in the response body of -a request to the [Charge](/doc/api/transactions.md#charge) endpoint. +a request to the [Charge]($e/Transactions/Charge) endpoint. One of `errors` or `transaction` is present in a given response (never both). diff --git a/doc/models/complete-payment-request.md b/doc/models/complete-payment-request.md new file mode 100644 index 00000000..6c02a4f9 --- /dev/null +++ b/doc/models/complete-payment-request.md @@ -0,0 +1,25 @@ + +# Complete Payment Request + +Describes a request to complete (capture) a payment using +[CompletePayment](/doc/api/payments.md#complete-payment). + +By default, payments are set to `autocomplete` immediately after they are created. +To complete payments manually, set `autocomplete` to `false`. + +## Structure + +`Complete Payment Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `version_token` | `string` | Optional | Used for optimistic concurrency. This opaque token identifies the current `Payment`
version that the caller expects. If the server has a different version of the Payment,
the update fails and a response with a VERSION_MISMATCH error is returned. | + +## Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/complete-payment-response.md b/doc/models/complete-payment-response.md index 58dc8ab8..5cb4de79 100644 --- a/doc/models/complete-payment-response.md +++ b/doc/models/complete-payment-response.md @@ -20,56 +20,69 @@ Defines the response returned by[CompletePayment](/doc/api/payments.md#complete- { "payment": { "amount_money": { - "amount": 200, + "amount": 555, "currency": "USD" }, - "app_fee_money": { - "amount": 10, - "currency": "USD" + "application_details": { + "application_id": "sq0ids-Pw67AZAlLVB7hsRmwlJPuA", + "square_product": "VIRTUAL_TERMINAL" }, "approved_money": { - "amount": 200, + "amount": 555, "currency": "USD" }, "card_details": { - "auth_result_code": "MhIjEN", + "auth_result_code": "2Nkw7q", "avs_status": "AVS_ACCEPTED", "card": { "bin": "411111", "card_brand": "VISA", "card_type": "DEBIT", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw", - "last_4": "2796", - "prepaid_type": "PREPAID" + "exp_month": 11, + "exp_year": 2022, + "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ", + "last_4": "1111", + "prepaid_type": "NOT_PREPAID" }, "card_payment_timeline": { - "authorized_at": "2019-07-10T13:23:49.234Z", - "captured_at": "2019-07-10T13:23:49.446Z" + "authorized_at": "2021-10-13T19:34:33.680Z", + "captured_at": "2021-10-13T19:34:34.340Z" }, "cvv_status": "CVV_ACCEPTED", - "entry_method": "ON_FILE", - "statement_description": "SQ *MY MERCHANT", + "entry_method": "KEYED", + "statement_description": "SQ *EXAMPLE TEST GOSQ.C", "status": "CAPTURED" }, - "created_at": "2019-07-10T13:39:55.317Z", - "customer_id": "RDX9Z4XTIZR7MRZJUXNY9HUK6I", - "id": "GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", - "location_id": "XTI0H92143A39", - "note": "Brief description", - "order_id": "m2Hr8Hk8A3CTyQQ1k4ynExg92tO3", - "receipt_number": "GQTF", - "receipt_url": "https://squareup.com/receipt/preview/GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", - "reference_id": "123456", + "created_at": "2021-10-13T19:34:33.524Z", + "delay_action": "CANCEL", + "delay_duration": "PT168H", + "delayed_until": "2021-10-20T19:34:33.524Z", + "employee_id": "TMoK_ogh6rH1o4dV", + "id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", + "location_id": "L88917AVBK2S5", + "note": "Test Note", + "order_id": "d7eKah653Z579f3gVtjlxpSlmUcZY", + "processing_fee": [ + { + "amount_money": { + "amount": 34, + "currency": "USD" + }, + "effective_at": "2021-10-13T21:34:35.000Z", + "type": "INITIAL" + } + ], + "receipt_number": "bP9m", + "receipt_url": "https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", "source_type": "CARD", "status": "COMPLETED", + "team_member_id": "TMoK_ogh6rH1o4dV", "total_money": { - "amount": 200, + "amount": 555, "currency": "USD" }, - "updated_at": "2019-07-10T13:40:05.982Z", - "version_token": "7knzZI16u3QBh2xXD7FH4GFwESqgam7Z9w2Ya0aSD9i6o" + "updated_at": "2021-10-13T19:34:34.339Z", + "version_token": "56pRkL3slrzet2iQrTp9n0bdJVYTB9YEWdTNjQfZOPV6o" } } ``` diff --git a/doc/models/create-customer-request.md b/doc/models/create-customer-request.md index 9cd37555..b74a1c4b 100644 --- a/doc/models/create-customer-request.md +++ b/doc/models/create-customer-request.md @@ -23,6 +23,7 @@ Defines the body parameters that can be included in a request to the | `reference_id` | `string` | Optional | An optional second ID used to associate the customer profile with an
entity in another system. | | `note` | `string` | Optional | A custom note associated with the customer profile. | | `birthday` | `string` | Optional | The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed.
For example, `0000-09-21T00:00:00-00:00` represents a birthday on September 21 and `1998-09-21T00:00:00-00:00` represents a birthday on September 21, 1998.
You can also specify this value in `YYYY-MM-DD` format. | +| `tax_ids` | [`Customer Tax Ids`](/doc/models/customer-tax-ids.md) | Optional | Represents the tax ID associated with a customer profile. The corresponding `tax_ids` field is available only for customers of sellers in France, Ireland, or the United Kingdom.
For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). | ## Example (as JSON) diff --git a/doc/models/create-location-request.md b/doc/models/create-location-request.md index 316c51c6..80e372b8 100644 --- a/doc/models/create-location-request.md +++ b/doc/models/create-location-request.md @@ -11,7 +11,7 @@ Request object for the [CreateLocation](/doc/api/locations.md#create-location) e | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `location` | [`Location`](/doc/models/location.md) | Optional | - | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | ## Example (as JSON) diff --git a/doc/models/create-location-response.md b/doc/models/create-location-response.md index 4d0a485a..d647602f 100644 --- a/doc/models/create-location-response.md +++ b/doc/models/create-location-response.md @@ -12,7 +12,7 @@ Response object returned by the [CreateLocation](/doc/api/locations.md#create-lo | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `location` | [`Location`](/doc/models/location.md) | Optional | - | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | ## Example (as JSON) diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index 2cb63e3b..7dfd9aa4 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -22,6 +22,7 @@ Describes a request to create a payment using | `order_id` | `string` | Optional | Associates a previously created order with this payment. | | `customer_id` | `string` | Optional | The [Customer](/doc/models/customer.md) ID of the customer associated with the payment.

This is required if the `source_id` refers to a card on file created using the Customers API. | | `location_id` | `string` | Optional | The location ID to associate with the payment. If not specified, the default location is
used. | +| `team_member_id` | `string` | Optional | An optional [TeamMember](/doc/models/team-member.md) ID to associate with
this payment. | | `reference_id` | `string` | Optional | A user-defined ID to associate with the payment.

You can use this field to associate the payment to an entity in an external system
(for example, you might specify an order ID that is generated by a third-party shopping cart).

Limit 40 characters.
**Constraints**: *Maximum Length*: `40` | | `verification_token` | `string` | Optional | An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity.

For more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview). | | `accept_partial_authorization` | `bool` | Optional | If set to `true` and charging a Square Gift Card, a payment might be returned with
`amount_money` equal to less than what was requested. For example, a request for $20 when charging
a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose
to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card
payment. This field cannot be `true` when `autocomplete = true`.

For more information, see
[Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

Default: false | @@ -38,7 +39,7 @@ Describes a request to create a payment using ```json { "amount_money": { - "amount": 200, + "amount": 1000, "currency": "USD" }, "app_fee_money": { @@ -46,12 +47,12 @@ Describes a request to create a payment using "currency": "USD" }, "autocomplete": true, - "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8", - "idempotency_key": "4935a656-a929-4792-b97c-8848be85c27c", - "location_id": "XK3DBG77NJBFX", + "customer_id": "W92WH6P11H4Z77CTET0RNTGFW8", + "idempotency_key": "7b0f3ec5-086a-4871-8f13-3c81b3875218", + "location_id": "L88917AVBK2S5", "note": "Brief description", "reference_id": "123456", - "source_id": "ccof:uIbfJXhXETSP197M3GB" + "source_id": "ccof:GaJGNaZa8x4OgDJn4GB" } ``` diff --git a/doc/models/create-payment-response.md b/doc/models/create-payment-response.md index b38bd367..ed5e4aeb 100644 --- a/doc/models/create-payment-response.md +++ b/doc/models/create-payment-response.md @@ -23,56 +23,67 @@ present, or it might be present with a status of `FAILED`. { "payment": { "amount_money": { - "amount": 200, + "amount": 1000, "currency": "USD" }, "app_fee_money": { "amount": 10, "currency": "USD" }, + "application_details": { + "application_id": "sq0ids-TcgftTEtKxJTRF1lCFJ9TA", + "square_product": "ECOMMERCE_API" + }, "approved_money": { - "amount": 200, + "amount": 1000, "currency": "USD" }, "card_details": { - "auth_result_code": "nsAyY2", + "auth_result_code": "vNEn2f", "avs_status": "AVS_ACCEPTED", "card": { "bin": "411111", "card_brand": "VISA", "card_type": "DEBIT", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw", + "exp_month": 11, + "exp_year": 2022, + "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ", "last_4": "1111", - "prepaid_type": "PREPAID" + "prepaid_type": "NOT_PREPAID" }, "card_payment_timeline": { - "authorized_at": "2019-07-10T13:23:49.234Z", - "captured_at": "2019-07-10T13:23:49.446Z" + "authorized_at": "2021-10-13T21:14:29.732Z", + "captured_at": "2021-10-13T21:14:30.504Z" }, "cvv_status": "CVV_ACCEPTED", "entry_method": "ON_FILE", - "statement_description": "SQ *MY MERCHANT", + "statement_description": "SQ *EXAMPLE TEST GOSQ.C", "status": "CAPTURED" }, - "created_at": "2019-07-10T13:23:49.154Z", - "customer_id": "RDX9Z4XTIZR7MRZJUXNY9HUK6I", - "id": "GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", - "location_id": "XTI0H92143A39", - "note": "Brief description", - "order_id": "m2Hr8Hk8A3CTyQQ1k4ynExg92tO3", - "receipt_number": "GQTF", - "receipt_url": "https://squareup.com/receipt/preview/GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", + "created_at": "2021-10-13T21:14:29.577Z", + "customer_id": "W92WH6P11H4Z77CTET0RNTGFW8", + "delay_action": "CANCEL", + "delay_duration": "PT168H", + "delayed_until": "2021-10-20T21:14:29.577Z", + "id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY", + "location_id": "L88917AVBK2S5", + "note": "Brief Description", + "order_id": "pRsjRTgFWATl7so6DxdKBJa7ssbZY", + "receipt_number": "R2B3", + "receipt_url": "https://squareupstaging.com/receipt/preview/R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY", "reference_id": "123456", + "risk_evaluation": { + "created_at": "2021-10-13T21:14:30.423Z", + "risk_level": "NORMAL" + }, "source_type": "CARD", "status": "COMPLETED", "total_money": { - "amount": 200, + "amount": 1000, "currency": "USD" }, - "updated_at": "2019-07-10T13:23:49.446Z", - "version_token": "H8Vnk5Z11SKcueuRti79jGpszSEsSVdhKRrSKCOzILG6o" + "updated_at": "2021-10-13T21:14:30.504Z", + "version_token": "TPtNEOBOa6Qq6E3C3IjckSVOM6b3hMbfhjvTxHBQUsB6o" } } ``` diff --git a/doc/models/create-refund-request.md b/doc/models/create-refund-request.md index b9ce3512..8f86478a 100644 --- a/doc/models/create-refund-request.md +++ b/doc/models/create-refund-request.md @@ -2,7 +2,7 @@ # Create Refund Request Defines the body parameters that can be included in -a request to the [CreateRefund](/doc/api/transactions.md#create-refund) endpoint. +a request to the [CreateRefund]($e/Transactions/CreateRefund) endpoint. Deprecated - recommend using [RefundPayment](/doc/api/refunds.md#refund-payment) diff --git a/doc/models/create-refund-response.md b/doc/models/create-refund-response.md index ecc9af02..1ed61e28 100644 --- a/doc/models/create-refund-response.md +++ b/doc/models/create-refund-response.md @@ -2,7 +2,7 @@ # Create Refund Response Defines the fields that are included in the response body of -a request to the [CreateRefund](/doc/api/transactions.md#create-refund) endpoint. +a request to the [CreateRefund]($e/Transactions/CreateRefund) endpoint. One of `errors` or `refund` is present in a given response (never both). diff --git a/doc/models/create-subscription-request.md b/doc/models/create-subscription-request.md index 25e2b8a8..cd468e92 100644 --- a/doc/models/create-subscription-request.md +++ b/doc/models/create-subscription-request.md @@ -22,6 +22,7 @@ Defines parameters in a | `price_override_money` | [`Money`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | | `card_id` | `string` | Optional | The ID of the [customer](/doc/models/customer.md) [card](/doc/models/card.md) to charge.
If not specified, Square sends an invoice via email. For an example to
create a customer and add a card on file, see [Subscriptions Walkthrough](https://developer.squareup.com/docs/subscriptions-api/walkthrough). | | `timezone` | `string` | Optional | The timezone that is used in date calculations for the subscription. If unset, defaults to
the location timezone. If a timezone is not configured for the location, defaults to "America/New_York".
Format: the IANA Timezone Database identifier for the location timezone. For
a list of time zones, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | +| `source` | [`Subscription Source`](/doc/models/subscription-source.md) | Optional | The origination details of the subscription. | ## Example (as JSON) @@ -36,7 +37,10 @@ Defines parameters in a "amount": 100, "currency": "USD" }, - "start_date": "2020-08-01", + "source": { + "name": "My App" + }, + "start_date": "2021-10-20", "tax_percentage": "5", "timezone": "America/Los_Angeles" } diff --git a/doc/models/create-subscription-response.md b/doc/models/create-subscription-response.md index 7ac850a4..05050de5 100644 --- a/doc/models/create-subscription-response.md +++ b/doc/models/create-subscription-response.md @@ -21,7 +21,7 @@ Defines the fields that are included in the response from the { "subscription": { "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB", - "created_at": "2020-08-03T21:53:10Z", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "56214fb2-cc85-47a1-93bc-44f3766bb56f", "location_id": "S8GWD5R9QB376", @@ -30,7 +30,10 @@ Defines the fields that are included in the response from the "amount": 100, "currency": "USD" }, - "start_date": "2020-08-01", + "source": { + "name": "My App" + }, + "start_date": "2021-10-20", "status": "PENDING", "tax_percentage": "5", "timezone": "America/Los_Angeles", diff --git a/doc/models/customer-tax-ids.md b/doc/models/customer-tax-ids.md new file mode 100644 index 00000000..29c02fae --- /dev/null +++ b/doc/models/customer-tax-ids.md @@ -0,0 +1,24 @@ + +# Customer Tax Ids + +Represents the tax ID associated with a customer profile. The corresponding `tax_ids` field is available only for customers of sellers in France, Ireland, or the United Kingdom. +For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). + +## Structure + +`Customer Tax Ids` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `eu_vat` | `string` | Optional | The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only.
**Constraints**: *Maximum Length*: `20` | + +## Example (as JSON) + +```json +{ + "eu_vat": "eu_vat2" +} +``` + diff --git a/doc/models/customer.md b/doc/models/customer.md index 521566d4..7756e029 100644 --- a/doc/models/customer.md +++ b/doc/models/customer.md @@ -30,6 +30,7 @@ Represents a Square customer profile in the Customer Directory of a Square selle | `group_ids` | `List of string` | Optional | The IDs of customer groups the customer belongs to. | | `segment_ids` | `List of string` | Optional | The IDs of segments the customer belongs to. | | `version` | `long\|int` | Optional | The Square-assigned version number of the customer profile. The version number is incremented each time an update is committed to the customer profile, except for changes to customer segment membership and cards on file. | +| `tax_ids` | [`Customer Tax Ids`](/doc/models/customer-tax-ids.md) | Optional | Represents the tax ID associated with a customer profile. The corresponding `tax_ids` field is available only for customers of sellers in France, Ireland, or the United Kingdom.
For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). | ## Example (as JSON) diff --git a/doc/models/get-payment-refund-response.md b/doc/models/get-payment-refund-response.md index 1c26c102..4dfb48c8 100644 --- a/doc/models/get-payment-refund-response.md +++ b/doc/models/get-payment-refund-response.md @@ -23,26 +23,27 @@ present or it might be present in a FAILED state. { "refund": { "amount_money": { - "amount": 1000, + "amount": 555, "currency": "USD" }, - "created_at": "2019-07-06T18:01:22.123Z", - "id": "O2QAAhTYs7rUfzlxT38GMO7LvaB_q7JwCHtxmgXrh8fAhV468WQ44VxDtL7CU4yVRlsbXmI", - "location_id": "XK3DBG77NJBFX", - "order_id": "2duiyoqbfeXY0DBi15GEyk5Epa4F", - "payment_id": "O2QAAhTYs7rUfzlxT38GMO7LvaB", + "created_at": "2021-10-13T19:59:05.073Z", + "id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY_69MmgHubkLqx9wGhnmenRUHOaKitE6llfZuxcWYjGxd", + "location_id": "L88917AVBK2S5", + "order_id": "9ltv0bx5PuvGXUYHYHxYSKEqC3IZY", + "payment_id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", "processing_fee": [ { "amount_money": { - "amount": -59, + "amount": -34, "currency": "USD" }, - "effective_at": "2019-07-06T20:01:12.000Z", + "effective_at": "2021-10-13T21:34:35.000Z", "type": "INITIAL" } ], + "reason": "Example Refund", "status": "COMPLETED", - "updated_at": "2019-07-06T18:06:03.874Z" + "updated_at": "2021-10-13T20:00:02.442Z" } } ``` diff --git a/doc/models/get-payment-response.md b/doc/models/get-payment-response.md index 167627ce..c87408d3 100644 --- a/doc/models/get-payment-response.md +++ b/doc/models/get-payment-response.md @@ -20,66 +20,69 @@ Defines the response returned by [GetPayment](/doc/api/payments.md#get-payment). { "payment": { "amount_money": { - "amount": 200, + "amount": 555, "currency": "USD" }, - "app_fee_money": { - "amount": 10, - "currency": "USD" + "application_details": { + "application_id": "sq0ids-Pw67AZAlLVB7hsRmwlJPuA", + "square_product": "VIRTUAL_TERMINAL" }, "approved_money": { - "amount": 200, + "amount": 555, "currency": "USD" }, "card_details": { - "auth_result_code": "nsAyY2", + "auth_result_code": "2Nkw7q", "avs_status": "AVS_ACCEPTED", "card": { "bin": "411111", "card_brand": "VISA", "card_type": "DEBIT", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw", + "exp_month": 11, + "exp_year": 2022, + "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ", "last_4": "1111", - "prepaid_type": "PREPAID" + "prepaid_type": "NOT_PREPAID" }, "card_payment_timeline": { - "authorized_at": "2019-07-10T13:23:49.234Z", - "captured_at": "2019-07-10T13:23:49.446Z" + "authorized_at": "2021-10-13T19:34:33.680Z", + "captured_at": "2021-10-13T19:34:34.340Z" }, "cvv_status": "CVV_ACCEPTED", - "entry_method": "ON_FILE", - "statement_description": "SQ *MY MERCHANT", + "entry_method": "KEYED", + "statement_description": "SQ *EXAMPLE TEST GOSQ.C", "status": "CAPTURED" }, - "created_at": "2019-07-10T13:23:49.154Z", - "customer_id": "RDX9Z4XTIZR7MRZJUXNY9HUK6I", - "id": "GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", - "location_id": "XTI0H92143A39", - "note": "Brief description", - "order_id": "m2Hr8Hk8A3CTyQQ1k4ynExg92tO3", + "created_at": "2021-10-13T19:34:33.524Z", + "delay_action": "CANCEL", + "delay_duration": "PT168H", + "delayed_until": "2021-10-20T19:34:33.524Z", + "employee_id": "TMoK_ogh6rH1o4dV", + "id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", + "location_id": "L88917AVBK2S5", + "note": "Test Note", + "order_id": "d7eKah653Z579f3gVtjlxpSlmUcZY", "processing_fee": [ { "amount_money": { - "amount": 36, + "amount": 34, "currency": "USD" }, - "effective_at": "2019-07-10T15:23:49.000Z", + "effective_at": "2021-10-13T21:34:35.000Z", "type": "INITIAL" } ], - "receipt_number": "GQTF", - "receipt_url": "https://squareup.com/receipt/preview/GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", - "reference_id": "123456", + "receipt_number": "bP9m", + "receipt_url": "https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", "source_type": "CARD", "status": "COMPLETED", + "team_member_id": "TMoK_ogh6rH1o4dV", "total_money": { - "amount": 200, + "amount": 555, "currency": "USD" }, - "updated_at": "2019-07-10T13:23:49.446Z", - "version_token": "hj8JqHWu9R1Kkfu63UuIUmYc7zm6YFOt92g8d2fb9fz6o" + "updated_at": "2021-10-13T19:34:34.339Z", + "version_token": "56pRkL3slrzet2iQrTp9n0bdJVYTB9YEWdTNjQfZOPV6o" } } ``` diff --git a/doc/models/invoice-recipient-tax-ids.md b/doc/models/invoice-recipient-tax-ids.md new file mode 100644 index 00000000..ffcd43a6 --- /dev/null +++ b/doc/models/invoice-recipient-tax-ids.md @@ -0,0 +1,25 @@ + +# Invoice Recipient Tax Ids + +Represents the tax IDs for an invoice recipient. The country of the seller account determines +whether the corresponding `tax_ids` field is available for the customer. For more information, +see [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids). + +## Structure + +`Invoice Recipient Tax Ids` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `eu_vat` | `string` | Optional | The EU VAT identification number for the invoice recipient. For example, `IE3426675K`. | + +## Example (as JSON) + +```json +{ + "eu_vat": "eu_vat2" +} +``` + diff --git a/doc/models/invoice-recipient.md b/doc/models/invoice-recipient.md index 5b2516d5..e4ac019e 100644 --- a/doc/models/invoice-recipient.md +++ b/doc/models/invoice-recipient.md @@ -1,7 +1,12 @@ # Invoice Recipient -Provides customer data that Square uses to deliver an invoice. +Represents a snapshot of customer data. This object stores customer data that is displayed on the invoice +and that Square uses to deliver the invoice. + +When you provide a customer ID for a draft invoice, Square retrieves the associated customer profile and populates +the remaining `InvoiceRecipient` fields. You cannot update these fields after the invoice is published. +Square updates the customer ID in response to a merge operation, but does not update other fields. ## Structure @@ -18,6 +23,7 @@ Provides customer data that Square uses to deliver an invoice. | `address` | [`Address`](/doc/models/address.md) | Optional | Represents a postal address in a country. The address format is based
on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
`Address` object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.

For the remaining address components, the `Address` type provides the
`address_line_1` and `address_line_2` fields for free-form data entry.
These fields are free-form because the remaining address components have
too many variations around the world and typical software does not parse
these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other `Address` type fields are blank.
These include `address_line_3`, `sublocality_2`, `sublocality_3`,
`administrative_district_level_2`, `administrative_district_level_3`,
`first_name`, `last_name`, and `organization`.

When it comes to localization, the seller's language preferences
(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
are ignored for addresses. Even though Square products (such as Square Point of Sale
and the Seller Dashboard) mostly use a seller's language preference in
communication, when it comes to addresses, they will use English for a US address,
Japanese for an address in Japan, and so on. | | `phone_number` | `string` | Optional | The recipient's phone number. | | `company_name` | `string` | Optional | The name of the recipient's company. | +| `tax_ids` | [`Invoice Recipient Tax Ids`](/doc/models/invoice-recipient-tax-ids.md) | Optional | Represents the tax IDs for an invoice recipient. The country of the seller account determines
whether the corresponding `tax_ids` field is available for the customer. For more information,
see [Invoice recipient tax IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids). | ## Example (as JSON) diff --git a/doc/models/invoice.md b/doc/models/invoice.md index 2ee4e038..54b52fb6 100644 --- a/doc/models/invoice.md +++ b/doc/models/invoice.md @@ -16,7 +16,7 @@ invoices. For more information, see [Manage Invoices Using the Invoices API](htt | `version` | `int` | Optional | The Square-assigned version number, which is incremented each time an update is committed to the invoice. | | `location_id` | `string` | Optional | The ID of the location that this invoice is associated with.

If specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `255` | | `order_id` | `string` | Optional | The ID of the [order](/doc/models/order.md) for which the invoice is created.
This field is required when creating an invoice, and the order must be in the `OPEN` state.

To view the line items and other information for the associated order, call the
[RetrieveOrder](/doc/api/orders.md#retrieve-order) endpoint using the order ID.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `255` | -| `primary_recipient` | [`Invoice Recipient`](/doc/models/invoice-recipient.md) | Optional | Provides customer data that Square uses to deliver an invoice. | +| `primary_recipient` | [`Invoice Recipient`](/doc/models/invoice-recipient.md) | Optional | Represents a snapshot of customer data. This object stores customer data that is displayed on the invoice
and that Square uses to deliver the invoice.

When you provide a customer ID for a draft invoice, Square retrieves the associated customer profile and populates
the remaining `InvoiceRecipient` fields. You cannot update these fields after the invoice is published.
Square updates the customer ID in response to a merge operation, but does not update other fields. | | `payment_requests` | [`List of Invoice Payment Request`](/doc/models/invoice-payment-request.md) | Optional | The payment schedule for the invoice, represented by one or more payment requests that
define payment settings, such as amount due and due date. An invoice supports the following payment request combinations:

- One balance
- One deposit with one balance
- 2–12 installments
- One deposit with 2–12 installments

This field is required when creating an invoice. It must contain at least one payment request.
All payment requests for the invoice must equal the total order amount. For more information, see
[Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests).

Adding `INSTALLMENT` payment requests to an invoice requires an
[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription). | | `delivery_method` | [`str (Invoice Delivery Method)`](/doc/models/invoice-delivery-method.md) | Optional | Indicates how Square delivers the [invoice](/doc/models/invoice.md) to the customer. | | `invoice_number` | `string` | Optional | A user-friendly invoice number. The value is unique within a location.
If not provided when creating an invoice, Square assigns a value.
It increments from 1 and padded with zeros making it 7 characters long
(for example, 0000001 and 0000002).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | diff --git a/doc/models/list-payment-refunds-response.md b/doc/models/list-payment-refunds-response.md index bd537dea..9910ecd2 100644 --- a/doc/models/list-payment-refunds-response.md +++ b/doc/models/list-payment-refunds-response.md @@ -25,49 +25,27 @@ Either `errors` or `refunds` is present in a given response (never both). "refunds": [ { "amount_money": { - "amount": 1000, + "amount": 555, "currency": "USD" }, - "created_at": "2019-07-06T18:01:22.335Z", - "id": "O2QAAhTYs7rUfzlxT38GMO7LvaB_q7JwCHtxmgXrh8fAhV468WQ44VxDtL7CU4yVRlsbXmI", - "location_id": "XK3DBG77NJBFX", - "order_id": "2duiyoqbfeXY0DBi15GEyk5Epa4F", - "payment_id": "O2QAAhTYs7rUfzlxT38GMO7LvaB", + "created_at": "2021-10-13T19:59:05.342Z", + "id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY_69MmgHubkLqx9wGhnmenRUHOaKitE6llfZuxcWYjGxd", + "location_id": "L88917AVBK2S5", + "order_id": "9ltv0bx5PuvGXUYHYHxYSKEqC3IZY", + "payment_id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", "processing_fee": [ { "amount_money": { - "amount": -59, + "amount": -34, "currency": "USD" }, - "effective_at": "2019-07-06T20:01:12.000Z", + "effective_at": "2021-10-13T21:34:35.000Z", "type": "INITIAL" } ], + "reason": "Example Refund", "status": "COMPLETED", - "updated_at": "2019-07-06T18:06:04.653Z" - }, - { - "amount_money": { - "amount": 1000, - "currency": "USD" - }, - "created_at": "2019-07-06T17:01:54.232Z", - "id": "8TDIQvFw8PeDIxhSfd5yyX7GuaB_13px5Vrz01qzzuoGzmjsZIxDjfHhbkm2XppBUX1dW7I", - "location_id": "XK3DBG77NJBFX", - "order_id": "w6EXfEwS03oTQsnZTCqfE6f67e4F", - "payment_id": "8TDIQvFw8PeDIxhSfd5yyX7GuaB", - "processing_fee": [ - { - "amount_money": { - "amount": -59, - "currency": "USD" - }, - "effective_at": "2019-07-06T19:01:45.000Z", - "type": "INITIAL" - } - ], - "status": "COMPLETED", - "updated_at": "2019-07-06T17:21:04.684Z" + "updated_at": "2021-10-13T20:00:03.497Z" } ] } diff --git a/doc/models/list-payments-response.md b/doc/models/list-payments-response.md index 7ee8fad6..82c7a236 100644 --- a/doc/models/list-payments-response.md +++ b/doc/models/list-payments-response.md @@ -19,103 +19,72 @@ Defines the response returned by [ListPayments](/doc/api/payments.md#list-paymen ```json { - "cursor": "2TTnuq0yRYDdBRSFF2XuFkgO1Bclt4ZHNI7YrFNeyZ6rL1WZXkdnLn10H8fBIwFKdKW1Af6ifRa", "payments": [ { "amount_money": { - "amount": 1000, + "amount": 555, "currency": "USD" }, + "application_details": { + "application_id": "sq0ids-Pw67AZAlLVB7hsRmwlJPuA", + "square_product": "VIRTUAL_TERMINAL" + }, "approved_money": { - "amount": 1000, + "amount": 555, "currency": "USD" }, - "capabilities": [ - "EDIT_AMOUNT_UP", - "EDIT_AMOUNT_DOWN", - "EDIT_TIP_AMOUNT_UP", - "EDIT_TIP_AMOUNT_DOWN" - ], "card_details": { - "auth_result_code": "NQbV3A", + "auth_result_code": "2Nkw7q", "avs_status": "AVS_ACCEPTED", "card": { + "bin": "411111", "card_brand": "VISA", - "exp_month": 2, + "card_type": "DEBIT", + "exp_month": 11, "exp_year": 2022, - "fingerprint": "sq-1-lHpUJIUyqOPQmH89b6GuQEljmc-mZmu4kSTaMlkLDkJI7NVjAl4Zirn2sk3OeyVKVA", - "last_4": "1111" + "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ", + "last_4": "1111", + "prepaid_type": "NOT_PREPAID" }, "card_payment_timeline": { - "authorized_at": "2019-07-09T14:36:13.798Z" + "authorized_at": "2021-10-13T19:34:33.680Z", + "captured_at": "2021-10-13T19:34:34.340Z" }, "cvv_status": "CVV_ACCEPTED", "entry_method": "KEYED", - "status": "AUTHORIZED" - }, - "created_at": "2019-07-09T14:36:13.745Z", - "id": "ifrBnAil7rRfDtd27cdf9g9WO8paB", - "location_id": "QLIJX16Q3UZ0A", - "order_id": "MvfIilKnIYKBium4rauH67wFzRxv", - "source_type": "CARD", - "status": "APPROVED", - "total_money": { - "amount": 1000, - "currency": "USD" - }, - "updated_at": "2019-07-09T14:36:13.883Z", - "version_token": "v6orqdHcW2TwuzCQRdF6a4ktbG8T8nbDcBx8eyrkoZl6o" - }, - { - "amount_money": { - "amount": 1000, - "currency": "USD" - }, - "approved_money": { - "amount": 1000, - "currency": "USD" - }, - "card_details": { - "auth_result_code": "vPIr0K", - "avs_status": "AVS_ACCEPTED", - "card": { - "card_brand": "VISA", - "exp_month": 7, - "exp_year": 2026, - "fingerprint": "sq-1-TpmjbNBMFdibiIjpQI5LiRgNUBC7u1689i0TgHjnlyHEWYB7tnn-K4QbW4ttvtaqXw", - "last_4": "2796" - }, - "card_payment_timeline": { - "authorized_at": "2019-07-08T01:00:51.617Z", - "captured_at": "2019-07-08T01:13:58.508Z" - }, - "cvv_status": "CVV_ACCEPTED", - "entry_method": "ON_FILE", + "statement_description": "SQ *EXAMPLE TEST GOSQ.C", "status": "CAPTURED" }, - "created_at": "2019-07-08T01:00:51.607Z", - "customer_id": "RDX9Z4XTIZR7MRZJUXNY9HUK6I", - "id": "GQTFp1ZlXdpoW4o6eGiZhbjosiDFf", - "location_id": "XTI0H92143A39", - "order_id": "m2Hr8Hk8A3CTyQQ1k4ynExg92tO3", + "created_at": "2021-10-13T19:34:33.524Z", + "delay_action": "CANCEL", + "delay_duration": "PT168H", + "delayed_until": "2021-10-20T19:34:33.524Z", + "employee_id": "TMoK_ogh6rH1o4dV", + "id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", + "location_id": "L88917AVBK2S5", + "note": "Test Note", + "order_id": "d7eKah653Z579f3gVtjlxpSlmUcZY", "processing_fee": [ { "amount_money": { - "amount": 59, + "amount": 34, "currency": "USD" }, - "effective_at": "2019-07-08T03:00:53.000Z", + "effective_at": "2021-10-13T21:34:35.000Z", "type": "INITIAL" } ], + "receipt_number": "bP9m", + "receipt_url": "https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY", "source_type": "CARD", "status": "COMPLETED", + "team_member_id": "TMoK_ogh6rH1o4dV", "total_money": { - "amount": 1000, + "amount": 555, "currency": "USD" }, - "updated_at": "2019-07-08T01:13:58.508Z", - "version_token": "pE0wanQBErcnO4ubL49pHCV1yAs4BUScWXb8fVvkRqa6o" + "updated_at": "2021-10-13T19:34:37.261Z", + "version_token": "vguW2km0KpVCdAXZcNTZ438qg5LlVPTP4HO5OpiHNfa6o" } ] } diff --git a/doc/models/list-refunds-request.md b/doc/models/list-refunds-request.md index 69c07707..4083079c 100644 --- a/doc/models/list-refunds-request.md +++ b/doc/models/list-refunds-request.md @@ -2,7 +2,7 @@ # List Refunds Request Defines the query parameters that can be included in -a request to the [ListRefunds](/doc/api/transactions.md#list-refunds) endpoint. +a request to the [ListRefunds]($e/Transactions/ListRefunds) endpoint. Deprecated - recommend using [SearchOrders](/doc/api/orders.md#search-orders) diff --git a/doc/models/list-refunds-response.md b/doc/models/list-refunds-response.md index 1f7464eb..d12e3c1e 100644 --- a/doc/models/list-refunds-response.md +++ b/doc/models/list-refunds-response.md @@ -2,7 +2,7 @@ # List Refunds Response Defines the fields that are included in the response body of -a request to the [ListRefunds](/doc/api/transactions.md#list-refunds) endpoint. +a request to the [ListRefunds]($e/Transactions/ListRefunds) endpoint. One of `errors` or `refunds` is present in a given response (never both). diff --git a/doc/models/location.md b/doc/models/location.md index 4510c995..9b8fc58e 100644 --- a/doc/models/location.md +++ b/doc/models/location.md @@ -1,6 +1,8 @@ # Location +Represents one of a business's locations. + ## Structure `Location` diff --git a/doc/models/obtain-token-response.md b/doc/models/obtain-token-response.md index 04df161e..217205b8 100644 --- a/doc/models/obtain-token-response.md +++ b/doc/models/obtain-token-response.md @@ -11,11 +11,11 @@ | --- | --- | --- | --- | | `access_token` | `string` | Optional | A valid OAuth access token. OAuth access tokens are 64 bytes long.
Provide the access token in a header with every request to Connect API
endpoints. See [OAuth API: Walkthrough](https://developer.squareup.com/docs/oauth-api/walkthrough)
for more information.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | | `token_type` | `string` | Optional | This value is always _bearer_.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `10` | -| `expires_at` | `string` | Optional | The date when access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | +| `expires_at` | `string` | Optional | The date when the access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | | `merchant_id` | `string` | Optional | The ID of the authorizing merchant's business.
**Constraints**: *Minimum Length*: `8`, *Maximum Length*: `191` | | `subscription_id` | `string` | Optional | __LEGACY FIELD__. The ID of a subscription plan the merchant signed up
for. Only present if the merchant signed up for a subscription during authorization. | | `plan_id` | `string` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. Only present if the merchant signed up for a subscription during
authorization. | -| `id_token` | `string` | Optional | Then OpenID token belonging to this person. Only present if the
OPENID scope is included in the authorization request. | +| `id_token` | `string` | Optional | The OpenID token belonging to this person. Only present if the
OPENID scope is included in the authorization request. | | `refresh_token` | `string` | Optional | A refresh token. OAuth refresh tokens are 64 bytes long.
For more information, see [Refresh, Revoke, and Limit the Scope of OAuth Tokens](https://developer.squareup.com/docs/oauth-api/refresh-revoke-limit-scope).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | | `short_lived` | `bool` | Optional | A boolean indicating the access token is a short-lived access token.
The short-lived access token returned in the response will expire in 24 hours. | diff --git a/doc/models/payment-refund.md b/doc/models/payment-refund.md index e7dea3fe..27dbae3e 100644 --- a/doc/models/payment-refund.md +++ b/doc/models/payment-refund.md @@ -23,6 +23,7 @@ the original payment and the amount of money refunded. | `reason` | `string` | Optional | The reason for the refund.
**Constraints**: *Maximum Length*: `192` | | `created_at` | `string` | Optional | The timestamp of when the refund was created, in RFC 3339 format.
**Constraints**: *Maximum Length*: `32` | | `updated_at` | `string` | Optional | The timestamp of when the refund was last updated, in RFC 3339 format.
**Constraints**: *Maximum Length*: `32` | +| `team_member_id` | `string` | Optional | An optional ID of the team member associated with taking the payment.
**Constraints**: *Maximum Length*: `192` | ## Example (as JSON) diff --git a/doc/models/payment.md b/doc/models/payment.md index e14b00ab..da07582c 100644 --- a/doc/models/payment.md +++ b/doc/models/payment.md @@ -35,7 +35,8 @@ Represents a payment processed by the Square API. | `order_id` | `string` | Optional | The ID of the order associated with the payment.
**Constraints**: *Maximum Length*: `192` | | `reference_id` | `string` | Optional | An optional ID that associates the payment with an entity in
another system.
**Constraints**: *Maximum Length*: `40` | | `customer_id` | `string` | Optional | The [Customer](/doc/models/customer.md) ID of the customer associated with the payment.
**Constraints**: *Maximum Length*: `191` | -| `employee_id` | `string` | Optional | An optional ID of the employee associated with taking the payment.
**Constraints**: *Maximum Length*: `192` | +| `employee_id` | `string` | Optional | __Deprecated__: Use `Payment.team_member_id` instead.

An optional ID of the employee associated with taking the payment.
**Constraints**: *Maximum Length*: `192` | +| `team_member_id` | `string` | Optional | An optional ID of the [TeamMember](/doc/models/team-member.md) associated with taking the payment.
**Constraints**: *Maximum Length*: `192` | | `refund_ids` | `List of string` | Optional | A list of `refund_id`s identifying refunds for the payment. | | `risk_evaluation` | [`Risk Evaluation`](/doc/models/risk-evaluation.md) | Optional | Represents fraud risk information for the associated payment.

When you take a payment through Square's Payments API (using the `CreatePayment`
endpoint), Square evaluates it and assigns a risk level to the payment. Sellers
can use this information to determine the course of action (for example,
provide the goods/services or refund the payment). | | `buyer_email_address` | `string` | Optional | The buyer's email address.
**Constraints**: *Maximum Length*: `255` | @@ -46,6 +47,8 @@ Represents a payment processed by the Square API. | `capabilities` | `List of string` | Optional | Actions that can be performed on this payment:

- `EDIT_AMOUNT_UP` - The payment amount can be edited up.
- `EDIT_AMOUNT_DOWN` - The payment amount can be edited down.
- `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up.
- `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down. | | `receipt_number` | `string` | Optional | The payment's receipt number.
The field is missing if a payment is canceled.
**Constraints**: *Maximum Length*: `4` | | `receipt_url` | `string` | Optional | The URL for the payment's receipt.
The field is only populated for COMPLETED payments.
**Constraints**: *Maximum Length*: `255` | +| `device_details` | [`Device Details`](/doc/models/device-details.md) | Optional | Details about the device that took the payment. | +| `application_details` | [`Application Details`](/doc/models/application-details.md) | Optional | Details about the application that took the payment. | | `version_token` | `string` | Optional | Used for optimistic concurrency. This opaque token identifies a specific version of the
`Payment` object. | ## Example (as JSON) diff --git a/doc/models/refund-payment-request.md b/doc/models/refund-payment-request.md index cd8cca2e..0287428c 100644 --- a/doc/models/refund-payment-request.md +++ b/doc/models/refund-payment-request.md @@ -16,17 +16,24 @@ Describes a request to refund a payment using [RefundPayment](/doc/api/refunds.m | `app_fee_money` | [`Money`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | | `payment_id` | `string` | Required | The unique ID of the payment being refunded.
**Constraints**: *Minimum Length*: `1` | | `reason` | `string` | Optional | A description of the reason for the refund.
**Constraints**: *Maximum Length*: `192` | +| `payment_version_token` | `string` | Optional | Used for optimistic concurrency. This opaque token identifies the current `Payment`
version that the caller expects. If the server has a different version of the Payment,
the update fails and a response with a VERSION_MISMATCH error is returned.
If the versions match, or the field is not provided, the refund proceeds as normal. | +| `team_member_id` | `string` | Optional | An optional [TeamMember](/doc/models/team-member.md) ID to associate with this refund.
**Constraints**: *Maximum Length*: `192` | ## Example (as JSON) ```json { "amount_money": { - "amount": 100, + "amount": 1000, "currency": "USD" }, - "idempotency_key": "a7e36d40-d24b-11e8-b568-0800200c9a66", - "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB" + "app_fee_money": { + "amount": 10, + "currency": "USD" + }, + "idempotency_key": "9b7f2dcf-49da-4411-b23e-a2d6af21333a", + "payment_id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY", + "reason": "Example" } ``` diff --git a/doc/models/refund-payment-response.md b/doc/models/refund-payment-response.md index 46c6b55e..97f8dee1 100644 --- a/doc/models/refund-payment-response.md +++ b/doc/models/refund-payment-response.md @@ -24,14 +24,21 @@ present, or it might be present with a status of `FAILED`. { "refund": { "amount_money": { - "amount": 100, + "amount": 1000, "currency": "USD" }, - "created_at": "2018-10-17T20:41:55.520Z", - "id": "UNOE3kv2BZwqHlJ830RCt5YCuaB_xVteEWVFkXDvKN1ddidfJWipt8p9whmElKT5mZtJ7wZ", - "payment_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB", + "app_fee_money": { + "amount": 10, + "currency": "USD" + }, + "created_at": "2021-10-13T21:23:19.116Z", + "id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY_KlWP8IC1557ddwc9QWTKrCVU6m0JXDz15R2Qym5eQfR", + "location_id": "L88917AVBK2S5", + "order_id": "1JLEUZeEooAIX8HMqm9kvWd69aQZY", + "payment_id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY", + "reason": "Example", "status": "PENDING", - "updated_at": "2018-10-17T20:41:55.520Z" + "updated_at": "2021-10-13T21:23:19.508Z" } } ``` diff --git a/doc/models/resume-subscription-response.md b/doc/models/resume-subscription-response.md index f2d6fd19..bb85e354 100644 --- a/doc/models/resume-subscription-response.md +++ b/doc/models/resume-subscription-response.md @@ -21,7 +21,7 @@ response. ```json { "subscription": { - "created_at": "2020-08-03T21:53:10Z", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "9ba40961-995a-4a3d-8c53-048c40cafc13", "location_id": "S8GWD5R9QB376", @@ -30,6 +30,9 @@ response. "amount": 2000, "currency": "USD" }, + "source": { + "name": "My App" + }, "status": "ACTIVE", "timezone": "America/Los_Angeles", "version": 1594311617331 diff --git a/doc/models/retrieve-location-response.md b/doc/models/retrieve-location-response.md index 4f24856a..f786f220 100644 --- a/doc/models/retrieve-location-response.md +++ b/doc/models/retrieve-location-response.md @@ -14,7 +14,7 @@ in a response. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `location` | [`Location`](/doc/models/location.md) | Optional | - | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | ## Example (as JSON) diff --git a/doc/models/retrieve-subscription-response.md b/doc/models/retrieve-subscription-response.md index 6f7d15b2..5f71db65 100644 --- a/doc/models/retrieve-subscription-response.md +++ b/doc/models/retrieve-subscription-response.md @@ -20,8 +20,8 @@ Defines the fields that are included in the response from the ```json { "subscription": { - "charged_through_date": "2020-06-11", - "created_at": "2020-08-03T21:53:10Z", + "charged_through_date": "2021-11-20", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "8151fc89-da15-4eb9-a685-1a70883cebfc", "invoice_ids": [ @@ -29,13 +29,16 @@ Defines the fields that are included in the response from the "rcX_i3sNmHTGKhI4W2mceA" ], "location_id": "S8GWD5R9QB376", - "paid_until_date": "2020-06-11", + "paid_until_date": "2021-11-20", "plan_id": "6JHXF3B2CW3YKHDV4XEM674H", "price_override_money": { "amount": 1000, "currency": "USD" }, - "start_date": "2020-05-11", + "source": { + "name": "My App" + }, + "start_date": "2021-10-20", "status": "ACTIVE", "timezone": "America/Los_Angeles" } diff --git a/doc/models/search-catalog-objects-request.md b/doc/models/search-catalog-objects-request.md index a55244ec..c5b22173 100644 --- a/doc/models/search-catalog-objects-request.md +++ b/doc/models/search-catalog-objects-request.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `string` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `object_types` | [`List of str (Catalog Object Type)`](/doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results. | +| `object_types` | [`List of str (Catalog Object Type)`](/doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results.

If not specified, the following catalog object types will be used as default:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | | `include_deleted_objects` | `bool` | Optional | If `true`, deleted objects will be included in the results. Deleted objects will have their
`is_deleted` field set to `true`. | | `include_related_objects` | `bool` | Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If a CatalogItem is returned in the object field of the response,
its associated CatalogCategory, CatalogTax objects,
CatalogImage objects and CatalogModifierList objects
will be included in the `related_objects` field of the response.

If a CatalogItemVariation is returned in the object field of the
response, its parent CatalogItem will be included in the `related_objects` field of
the response. | | `begin_time` | `string` | Optional | Return objects modified after this [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), in RFC 3339
format, e.g., `2016-09-04T23:59:33.123Z`. The timestamp is exclusive - objects with a
timestamp equal to `begin_time` will not be included in the response. | diff --git a/doc/models/search-subscriptions-filter.md b/doc/models/search-subscriptions-filter.md index f5ed4c08..39b74492 100644 --- a/doc/models/search-subscriptions-filter.md +++ b/doc/models/search-subscriptions-filter.md @@ -13,6 +13,7 @@ Represents a set of SearchSubscriptionsQuery filters used to limit the set of Su | --- | --- | --- | --- | | `customer_ids` | `List of string` | Optional | A filter to select subscriptions based on the customer. | | `location_ids` | `List of string` | Optional | A filter to select subscriptions based the location. | +| `source_names` | `List of string` | Optional | A filter to select subscriptions based on the source application. | ## Example (as JSON) @@ -24,6 +25,9 @@ Represents a set of SearchSubscriptionsQuery filters used to limit the set of Su ], "location_ids": [ "location_ids0" + ], + "source_names": [ + "source_names8" ] } ``` diff --git a/doc/models/search-subscriptions-query.md b/doc/models/search-subscriptions-query.md index e7780afd..d9421f40 100644 --- a/doc/models/search-subscriptions-query.md +++ b/doc/models/search-subscriptions-query.md @@ -24,6 +24,9 @@ Represents a query (including filtering criteria) used to search for subscriptio ], "location_ids": [ "location_ids4" + ], + "source_names": [ + "source_names2" ] } } diff --git a/doc/models/search-subscriptions-request.md b/doc/models/search-subscriptions-request.md index 20776243..d1e36670 100644 --- a/doc/models/search-subscriptions-request.md +++ b/doc/models/search-subscriptions-request.md @@ -28,6 +28,9 @@ request. ], "location_ids": [ "S8GWD5R9QB376" + ], + "source_names": [ + "My App" ] } } diff --git a/doc/models/search-subscriptions-response.md b/doc/models/search-subscriptions-response.md index 98d9da4a..262a3f87 100644 --- a/doc/models/search-subscriptions-response.md +++ b/doc/models/search-subscriptions-response.md @@ -22,21 +22,24 @@ Defines the fields that are included in the response from the { "subscriptions": [ { - "canceled_date": "2020-04-14", + "canceled_date": "2021-10-20", "card_id": "ccof:mueUsvgajChmjEbp4GB", - "charged_through_date": "2020-05-14", - "created_at": "2020-08-03T21:53:10Z", + "charged_through_date": "2021-11-20", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "de86fc96-8664-474b-af1a-abbe59cacf0e", "location_id": "S8GWD5R9QB376", - "paid_until_date": "2020-05-14", + "paid_until_date": "2021-11-20", "plan_id": "L3TJVDHVBEQEGQDEZL2JJM7R", - "start_date": "2020-04-14", + "source": { + "name": "My Application" + }, + "start_date": "2021-10-20", "status": "CANCELED", "timezone": "UTC" }, { - "created_at": "2020-08-03T21:53:10Z", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "56214fb2-cc85-47a1-93bc-44f3766bb56f", "location_id": "S8GWD5R9QB376", @@ -45,15 +48,18 @@ Defines the fields that are included in the response from the "amount": 100, "currency": "USD" }, - "start_date": "2020-08-01", + "source": { + "name": "My Application" + }, + "start_date": "2021-10-20", "status": "PENDING", "tax_percentage": "5", "timezone": "America/Los_Angeles", "version": 1594155459464 }, { - "charged_through_date": "2020-06-11", - "created_at": "2020-08-03T21:53:10Z", + "charged_through_date": "2021-11-20", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "8151fc89-da15-4eb9-a685-1a70883cebfc", "invoice_ids": [ @@ -61,13 +67,16 @@ Defines the fields that are included in the response from the "rcX_i3sNmHTGKhI4W2mceA" ], "location_id": "S8GWD5R9QB376", - "paid_until_date": "2020-06-11", + "paid_until_date": "2021-11-20", "plan_id": "6JHXF3B2CW3YKHDV4XEM674H", "price_override_money": { "amount": 1000, "currency": "USD" }, - "start_date": "2020-05-11", + "source": { + "name": "My Application" + }, + "start_date": "2021-10-20", "status": "ACTIVE", "timezone": "America/Los_Angeles" } diff --git a/doc/models/subscription-source.md b/doc/models/subscription-source.md new file mode 100644 index 00000000..7a9adec1 --- /dev/null +++ b/doc/models/subscription-source.md @@ -0,0 +1,23 @@ + +# Subscription Source + +The origination details of the subscription. + +## Structure + +`Subscription Source` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `name` | `string` | Optional | The name used to identify the place (physical or digital) that
a subscription originates. If unset, the name defaults to the name
of the application that created the subscription.
**Constraints**: *Maximum Length*: `255` | + +## Example (as JSON) + +```json +{ + "name": "name0" +} +``` + diff --git a/doc/models/subscription.md b/doc/models/subscription.md index 7537964b..61bb2f60 100644 --- a/doc/models/subscription.md +++ b/doc/models/subscription.md @@ -28,6 +28,7 @@ For an overview of the `Subscription` type, see | `created_at` | `string` | Optional | The timestamp when the subscription was created, in RFC 3339 format. | | `card_id` | `string` | Optional | The ID of the [customer](/doc/models/customer.md) [card](/doc/models/card.md)
that is charged for the subscription. | | `timezone` | `string` | Optional | Timezone that will be used in date calculations for the subscription.
Defaults to the timezone of the location based on `location_id`.
Format: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`). | +| `source` | [`Subscription Source`](/doc/models/subscription-source.md) | Optional | The origination details of the subscription. | ## Example (as JSON) diff --git a/doc/models/transaction.md b/doc/models/transaction.md index 07304353..d1340641 100644 --- a/doc/models/transaction.md +++ b/doc/models/transaction.md @@ -20,7 +20,7 @@ the transaction. | `created_at` | `string` | Optional | The timestamp for when the transaction was created, in RFC 3339 format.
**Constraints**: *Maximum Length*: `32` | | `tenders` | [`List of Tender`](/doc/models/tender.md) | Optional | The tenders used to pay in the transaction. | | `refunds` | [`List of Refund`](/doc/models/refund.md) | Optional | Refunds that have been applied to any tender in the transaction. | -| `reference_id` | `string` | Optional | If the transaction was created with the [Charge](/doc/api/transactions.md#charge)
endpoint, this value is the same as the value provided for the `reference_id`
parameter in the request to that endpoint. Otherwise, it is not set.
**Constraints**: *Maximum Length*: `40` | +| `reference_id` | `string` | Optional | If the transaction was created with the [Charge]($e/Transactions/Charge)
endpoint, this value is the same as the value provided for the `reference_id`
parameter in the request to that endpoint. Otherwise, it is not set.
**Constraints**: *Maximum Length*: `40` | | `product` | [`str (Transaction Product)`](/doc/models/transaction-product.md) | Optional | Indicates the Square product used to process a transaction. | | `client_id` | `string` | Optional | If the transaction was created in the Square Point of Sale app, this value
is the ID generated for the transaction by Square Point of Sale.

This ID has no relationship to the transaction's canonical `id`, which is
generated by Square's backend servers. This value is generated for bookkeeping
purposes, in case the transaction cannot immediately be completed (for example,
if the transaction is processed in offline mode).

It is not currently possible with the Connect API to perform a transaction
lookup by this value.
**Constraints**: *Maximum Length*: `192` | | `shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a postal address in a country. The address format is based
on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
`Address` object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.

For the remaining address components, the `Address` type provides the
`address_line_1` and `address_line_2` fields for free-form data entry.
These fields are free-form because the remaining address components have
too many variations around the world and typical software does not parse
these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other `Address` type fields are blank.
These include `address_line_3`, `sublocality_2`, `sublocality_3`,
`administrative_district_level_2`, `administrative_district_level_3`,
`first_name`, `last_name`, and `organization`.

When it comes to localization, the seller's language preferences
(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
are ignored for addresses. Even though Square products (such as Square Point of Sale
and the Seller Dashboard) mostly use a seller's language preference in
communication, when it comes to addresses, they will use English for a US address,
Japanese for an address in Japan, and so on. | diff --git a/doc/models/update-customer-request.md b/doc/models/update-customer-request.md index 285887c9..e52a1871 100644 --- a/doc/models/update-customer-request.md +++ b/doc/models/update-customer-request.md @@ -23,6 +23,7 @@ Defines the body parameters that can be included in a request to the | `note` | `string` | Optional | A custom note associated with the customer profile. | | `birthday` | `string` | Optional | The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed.
For example, `0000-09-21T00:00:00-00:00` represents a birthday on September 21 and `1998-09-21T00:00:00-00:00` represents a birthday on September 21, 1998.
You can also specify this value in `YYYY-MM-DD` format. | | `version` | `long\|int` | Optional | The current version of the customer profile.

As a best practice, you should include this field to enable [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency) control. For more information, see [Update a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#update-a-customer-profile). | +| `tax_ids` | [`Customer Tax Ids`](/doc/models/customer-tax-ids.md) | Optional | Represents the tax ID associated with a customer profile. The corresponding `tax_ids` field is available only for customers of sellers in France, Ireland, or the United Kingdom.
For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). | ## Example (as JSON) diff --git a/doc/models/update-location-request.md b/doc/models/update-location-request.md index e7dd702d..1a66d535 100644 --- a/doc/models/update-location-request.md +++ b/doc/models/update-location-request.md @@ -11,7 +11,7 @@ Request object for the [UpdateLocation](/doc/api/locations.md#update-location) e | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `location` | [`Location`](/doc/models/location.md) | Optional | - | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | ## Example (as JSON) diff --git a/doc/models/update-location-response.md b/doc/models/update-location-response.md index 9eb351cc..f259b1d5 100644 --- a/doc/models/update-location-response.md +++ b/doc/models/update-location-response.md @@ -12,7 +12,7 @@ Response object returned by the [UpdateLocation](/doc/api/locations.md#update-lo | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `location` | [`Location`](/doc/models/location.md) | Optional | - | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | ## Example (as JSON) diff --git a/doc/models/update-payment-request.md b/doc/models/update-payment-request.md index 85968c23..dae541e5 100644 --- a/doc/models/update-payment-request.md +++ b/doc/models/update-payment-request.md @@ -19,17 +19,17 @@ Describes a request to update a payment using ```json { - "idempotency_key": "3d3c3b22-9572-4fc6-1111-e4d2f41b4122", + "idempotency_key": "956f8b13-e4ec-45d6-85e8-d1d95ef0c5de", "payment": { "amount_money": { "amount": 1000, "currency": "USD" }, "tip_money": { - "amount": 300, + "amount": 100, "currency": "USD" }, - "version_token": "Z3okDzm2VRv5m5nE3WGx381ItTNhvjkB4VapByyz54h6o" + "version_token": "ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o" } } ``` diff --git a/doc/models/update-payment-response.md b/doc/models/update-payment-response.md index 6c988883..e5ed29ab 100644 --- a/doc/models/update-payment-response.md +++ b/doc/models/update-payment-response.md @@ -24,6 +24,10 @@ Defines the response returned by "amount": 1000, "currency": "USD" }, + "application_details": { + "application_id": "sq0ids-TcgftTEtKxJTRF1lCFJ9TA", + "square_product": "ECOMMERCE_API" + }, "approved_money": { "amount": 1000, "currency": "USD" @@ -35,45 +39,52 @@ Defines the response returned by "EDIT_TIP_AMOUNT_DOWN" ], "card_details": { - "auth_result_code": "ajM2ZF", + "auth_result_code": "68aLBM", "avs_status": "AVS_ACCEPTED", "card": { "bin": "411111", "card_brand": "VISA", - "card_type": "CREDIT", - "exp_month": 2, + "card_type": "DEBIT", + "exp_month": 11, "exp_year": 2022, - "fingerprint": "sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ", - "last_4": "1111" + "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ", + "last_4": "1111", + "prepaid_type": "NOT_PREPAID" }, "card_payment_timeline": { - "authorized_at": "2021-02-24T03:33:43.681Z" + "authorized_at": "2021-10-13T20:26:44.364Z" }, "cvv_status": "CVV_ACCEPTED", - "entry_method": "KEYED", - "statement_description": "SQ *MY BUSINESS GOSQ.COM", + "entry_method": "ON_FILE", + "statement_description": "SQ *EXAMPLE TEST GOSQ.C", "status": "AUTHORIZED" }, - "created_at": "2021-03-02T19:53:31.055Z", + "created_at": "2021-10-13T20:26:44.191Z", + "customer_id": "W92WH6P11H4Z77CTET0RNTGFW8", "delay_action": "CANCEL", "delay_duration": "PT168H", - "delayed_until": "2021-03-09T19:53:31.055Z", - "id": "XllelosAAfmkf9mOa0YB4PqSZACZY", - "location_id": "XTI0H92143A39", - "order_id": "B6qiKWus1d3TBoN2Qn5kfDiWZlfZY", - "receipt_number": "Xlle", + "delayed_until": "2021-10-20T20:26:44.191Z", + "id": "1QjqpBVyrI9S4H9sTGDWU9JeiWdZY", + "location_id": "L88917AVBK2S5", + "note": "Example Note", + "order_id": "nUSN9TdxpiK3SrQg3wzmf6r8LP9YY", + "receipt_number": "1Qjq", + "risk_evaluation": { + "created_at": "2021-10-13T20:26:45.271Z", + "risk_level": "NORMAL" + }, "source_type": "CARD", "status": "APPROVED", "tip_money": { - "amount": 300, + "amount": 100, "currency": "USD" }, "total_money": { - "amount": 1300, + "amount": 1100, "currency": "USD" }, - "updated_at": "2021-03-02T19:53:31.164Z", - "version_token": "9TKsTawsWZvdZZD5uhAZFWfd3chxFXB49cgFpD2Kujf6o" + "updated_at": "2021-10-13T20:26:44.364Z", + "version_token": "rDrXnqiS7fJgexccgdpzmwqTiXui1aIKCp9EchZ7trE6o" } } ``` diff --git a/doc/models/update-subscription-response.md b/doc/models/update-subscription-response.md index bf0ca475..8f6d724f 100644 --- a/doc/models/update-subscription-response.md +++ b/doc/models/update-subscription-response.md @@ -20,7 +20,7 @@ Defines the fields that are included in the response from the ```json { "subscription": { - "created_at": "2020-08-03T21:53:10Z", + "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", "id": "9ba40961-995a-4a3d-8c53-048c40cafc13", "location_id": "S8GWD5R9QB376", @@ -29,6 +29,9 @@ Defines the fields that are included in the response from the "amount": 2000, "currency": "USD" }, + "source": { + "name": "My App" + }, "status": "ACTIVE", "timezone": "America/Los_Angeles", "version": 1594311617331 diff --git a/setup.py b/setup.py index 3356624f..2fd5585b 100644 --- a/setup.py +++ b/setup.py @@ -12,7 +12,7 @@ setup( name='squareup', - version='14.1.1.20210915', + version='15.0.0.20211020', description='Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.', long_description=long_description, long_description_content_type="text/markdown", diff --git a/square/api/base_api.py b/square/api/base_api.py index 5e65e04b..12d14cc9 100644 --- a/square/api/base_api.py +++ b/square/api/base_api.py @@ -21,7 +21,7 @@ class BaseApi(object): def global_headers(self): return { - 'user-agent': 'Square-Python-SDK/14.1.1.20210915', + 'user-agent': 'Square-Python-SDK/15.0.0.20211020', 'Square-Version': self.config.square_version } diff --git a/square/api/customer_groups_api.py b/square/api/customer_groups_api.py index 405be32d..1b6c8b02 100644 --- a/square/api/customer_groups_api.py +++ b/square/api/customer_groups_api.py @@ -29,7 +29,7 @@ def list_customer_groups(self, pis/pagination). limit (int, optional): The maximum number of results to return in a single page. This limit is advisory. The response might - contain more or fewer results. The limit is ignored if it is + contain more or fewer results. The limit is ignored if it is less than 1 or greater than 50. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-a diff --git a/square/api/customer_segments_api.py b/square/api/customer_segments_api.py index b1dda360..a7429c5b 100644 --- a/square/api/customer_segments_api.py +++ b/square/api/customer_segments_api.py @@ -29,7 +29,7 @@ def list_customer_segments(self, pis/pagination). limit (int, optional): The maximum number of results to return in a single page. This limit is advisory. The response might - contain more or fewer results. The limit is ignored if it is + contain more or fewer results. The limit is ignored if it is less than 1 or greater than 50. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-a diff --git a/square/api/customers_api.py b/square/api/customers_api.py index 4fdebceb..583d62d9 100644 --- a/square/api/customers_api.py +++ b/square/api/customers_api.py @@ -38,7 +38,7 @@ def list_customers(self, pis/pagination). limit (int, optional): The maximum number of results to return in a single page. This limit is advisory. The response might - contain more or fewer results. The limit is ignored if it is + contain more or fewer results. The limit is ignored if it is less than 1 or greater than 100. The default value is 100. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-a diff --git a/square/api/payments_api.py b/square/api/payments_api.py index bfbbbb5c..f69bc7d3 100644 --- a/square/api/payments_api.py +++ b/square/api/payments_api.py @@ -386,7 +386,8 @@ def cancel_payment(self, return _result def complete_payment(self, - payment_id): + payment_id, + body): """Does a POST request to /v2/payments/{payment_id}/complete. Completes (captures) a payment. @@ -398,6 +399,9 @@ def complete_payment(self, Args: payment_id (string): The unique ID identifying the payment to be completed. + body (CompletePaymentRequest): An object containing the fields to + POST for the request. See the corresponding object definition + for field details. Returns: ApiResponse: An object with the response value as well as other @@ -422,11 +426,12 @@ def complete_payment(self, # Prepare headers _headers = { - 'accept': 'application/json' + 'accept': 'application/json', + 'content-type': 'application/json; charset=utf-8' } # Prepare and execute request - _request = self.config.http_client.post(_query_url, headers=_headers) + _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body)) OAuth2.apply(self.config, _request) _response = self.execute_request(_request) diff --git a/square/api/transactions_api.py b/square/api/transactions_api.py index f32d37b5..1886ac40 100644 --- a/square/api/transactions_api.py +++ b/square/api/transactions_api.py @@ -14,98 +14,6 @@ class TransactionsApi(BaseApi): def __init__(self, config, call_back=None): super(TransactionsApi, self).__init__(config, call_back) - @deprecated() - def list_refunds(self, - location_id, - begin_time=None, - end_time=None, - sort_order=None, - cursor=None): - """Does a GET request to /v2/locations/{location_id}/refunds. - - Lists refunds for one of a business's locations. - In addition to full or partial tender refunds processed through Square - APIs, - refunds may result from itemized returns or exchanges through - Square's - Point of Sale applications. - Refunds with a `status` of `PENDING` are not currently included in - this - endpoint's response. - Max results per - [page](https://developer.squareup.com/docs/working-with-apis/pagination - ): 50 - - Args: - location_id (string): The ID of the location to list refunds for. - begin_time (string, optional): The beginning of the requested - reporting period, in RFC 3339 format. See [Date - ranges](https://developer.squareup.com/docs/build-basics/workin - g-with-dates) for details on date inclusivity/exclusivity. - Default value: The current time minus one year. - end_time (string, optional): The end of the requested reporting - period, in RFC 3339 format. See [Date - ranges](https://developer.squareup.com/docs/build-basics/workin - g-with-dates) for details on date inclusivity/exclusivity. - Default value: The current time. - sort_order (SortOrder, optional): The order in which results are - listed in the response (`ASC` for oldest first, `DESC` for - newest first). Default value: `DESC` - cursor (string, optional): A pagination cursor returned by a - previous call to this endpoint. Provide this to retrieve the - next set of results for your original query. See [Paginating - results](https://developer.squareup.com/docs/working-with-apis/ - pagination) for more information. - - Returns: - ApiResponse: An object with the response value as well as other - useful information such as status codes and headers. Success - - Raises: - APIException: When an error occurs while fetching the data from - the remote API. This exception includes the HTTP Response - code, an error message, and the HTTP body that was received in - the request. - - """ - - # Prepare query URL - _url_path = '/v2/locations/{location_id}/refunds' - _url_path = APIHelper.append_url_with_template_parameters(_url_path, { - 'location_id': {'value': location_id, 'encode': True} - }) - _query_builder = self.config.get_base_uri() - _query_builder += _url_path - _query_parameters = { - 'begin_time': begin_time, - 'end_time': end_time, - 'sort_order': sort_order, - 'cursor': cursor - } - _query_builder = APIHelper.append_url_with_query_parameters( - _query_builder, - _query_parameters - ) - _query_url = APIHelper.clean_url(_query_builder) - - # Prepare headers - _headers = { - 'accept': 'application/json' - } - - # Prepare and execute request - _request = self.config.http_client.get(_query_url, headers=_headers) - OAuth2.apply(self.config, _request) - _response = self.execute_request(_request) - - decoded = APIHelper.json_deserialize(_response.text) - if type(decoded) is dict: - _errors = decoded.get('errors') - else: - _errors = None - _result = ApiResponse(_response, body=decoded, errors=_errors) - return _result - @deprecated() def list_transactions(self, location_id, @@ -194,82 +102,6 @@ def list_transactions(self, _result = ApiResponse(_response, body=decoded, errors=_errors) return _result - @deprecated() - def charge(self, - location_id, - body): - """Does a POST request to /v2/locations/{location_id}/transactions. - - Charges a card represented by a card nonce or a customer's card on - file. - Your request to this endpoint must include _either_: - - A value for the `card_nonce` parameter (to charge a card payment - token generated - with the Web Payments SDK) - - Values for the `customer_card_id` and `customer_id` parameters (to - charge - a customer's card on file) - In order for an eCommerce payment to potentially qualify for - [Square chargeback - protection](https://squareup.com/help/article/5394), you - _must_ provide values for the following parameters in your request: - - `buyer_email_address` - - At least one of `billing_address` or `shipping_address` - When this response is returned, the amount of Square's processing fee - might not yet be - calculated. To obtain the processing fee, wait about ten seconds and - call - [RetrieveTransaction]($e/Transactions/RetrieveTransaction). See the - `processing_fee_money` - field of each [Tender included]($m/Tender) in the transaction. - - Args: - location_id (string): The ID of the location to associate the - created transaction with. - body (ChargeRequest): An object containing the fields to POST for - the request. See the corresponding object definition for - field details. - - Returns: - ApiResponse: An object with the response value as well as other - useful information such as status codes and headers. Success - - Raises: - APIException: When an error occurs while fetching the data from - the remote API. This exception includes the HTTP Response - code, an error message, and the HTTP body that was received in - the request. - - """ - - # Prepare query URL - _url_path = '/v2/locations/{location_id}/transactions' - _url_path = APIHelper.append_url_with_template_parameters(_url_path, { - 'location_id': {'value': location_id, 'encode': True} - }) - _query_builder = self.config.get_base_uri() - _query_builder += _url_path - _query_url = APIHelper.clean_url(_query_builder) - - # Prepare headers - _headers = { - 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' - } - - # Prepare and execute request - _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body)) - OAuth2.apply(self.config, _request) - _response = self.execute_request(_request) - - decoded = APIHelper.json_deserialize(_response.text) - if type(decoded) is dict: - _errors = decoded.get('errors') - else: - _errors = None - _result = ApiResponse(_response, body=decoded, errors=_errors) - return _result - @deprecated() def retrieve_transaction(self, location_id, @@ -381,73 +213,6 @@ def capture_transaction(self, _result = ApiResponse(_response, body=decoded, errors=_errors) return _result - @deprecated() - def create_refund(self, - location_id, - transaction_id, - body): - """Does a POST request to /v2/locations/{location_id}/transactions/{transaction_id}/refund. - - Initiates a refund for a previously charged tender. - You must issue a refund within 120 days of the associated payment. - See - [this article](https://squareup.com/help/us/en/article/5060) for more - information - on refund behavior. - NOTE: Card-present transactions with Interac credit cards **cannot be - refunded using the Connect API**. Interac transactions must refunded - in-person (e.g., dipping the card using POS app). - - Args: - location_id (string): The ID of the original transaction's - associated location. - transaction_id (string): The ID of the original transaction that - includes the tender to refund. - body (CreateRefundRequest): An object containing the fields to - POST for the request. See the corresponding object definition - for field details. - - Returns: - ApiResponse: An object with the response value as well as other - useful information such as status codes and headers. Success - - Raises: - APIException: When an error occurs while fetching the data from - the remote API. This exception includes the HTTP Response - code, an error message, and the HTTP body that was received in - the request. - - """ - - # Prepare query URL - _url_path = '/v2/locations/{location_id}/transactions/{transaction_id}/refund' - _url_path = APIHelper.append_url_with_template_parameters(_url_path, { - 'location_id': {'value': location_id, 'encode': True}, - 'transaction_id': {'value': transaction_id, 'encode': True} - }) - _query_builder = self.config.get_base_uri() - _query_builder += _url_path - _query_url = APIHelper.clean_url(_query_builder) - - # Prepare headers - _headers = { - 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' - } - - # Prepare and execute request - _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body)) - OAuth2.apply(self.config, _request) - _response = self.execute_request(_request) - - decoded = APIHelper.json_deserialize(_response.text) - if type(decoded) is dict: - _errors = decoded.get('errors') - else: - _errors = None - _result = ApiResponse(_response, body=decoded, errors=_errors) - return _result - @deprecated() def void_transaction(self, location_id, diff --git a/square/client.py b/square/client.py index 174c4c01..d9a48e60 100644 --- a/square/client.py +++ b/square/client.py @@ -41,11 +41,11 @@ class Client(object): @staticmethod def sdk_version(): - return '14.1.1.20210915' + return '15.0.0.20211020' @staticmethod def square_version(): - return '2021-09-15' + return '2021-10-20' @lazy_property def mobile_authorization(self): @@ -183,7 +183,7 @@ def __init__(self, timeout=60, max_retries=0, backoff_factor=2, retry_statuses=[408, 413, 429, 500, 502, 503, 504, 521, 522, 524], retry_methods=['GET', 'PUT'], environment='production', custom_url='https://connect.squareup.com', - square_version='2021-09-15', access_token='TODO: Replace', + square_version='2021-10-20', access_token='TODO: Replace', additional_headers={}, config=None): if config is None: self.config = Configuration(timeout=timeout, diff --git a/square/configuration.py b/square/configuration.py index e95f4153..450e8bb7 100644 --- a/square/configuration.py +++ b/square/configuration.py @@ -57,7 +57,7 @@ def __init__( self, timeout=60, max_retries=0, backoff_factor=2, retry_statuses=[408, 413, 429, 500, 502, 503, 504, 521, 522, 524], retry_methods=['GET', 'PUT'], environment='production', - custom_url='https://connect.squareup.com', square_version='2021-09-15', + custom_url='https://connect.squareup.com', square_version='2021-10-20', access_token='TODO: Replace', additional_headers={} ): # The value to use for connection timeout