From ecf3cc73bee6b9f420718b0bc47a8d26078c2f80 Mon Sep 17 00:00:00 2001 From: autobot Date: Thu, 16 Jun 2022 15:37:30 +0000 Subject: [PATCH] Generated PR for Release: 19.1.0.20220616 --- CHANGELOG.md | 3 + composer.json | 4 +- doc/apis/catalog.md | 2 +- doc/apis/gift-cards.md | 2 +- doc/apis/loyalty.md | 6 +- doc/apis/terminal.md | 3 +- doc/client.md | 6 +- doc/models/appointment-segment.md | 8 +- ...atch-retrieve-inventory-changes-request.md | 5 +- ...batch-retrieve-inventory-counts-request.md | 1 + .../calculate-loyalty-points-response.md | 2 +- doc/models/cancel-terminal-action-response.md | 2 +- doc/models/card-co-brand.md | 17 + doc/models/card.md | 4 +- doc/models/catalog-subscription-plan.md | 10 +- .../create-gift-card-activity-request.md | 2 +- .../create-gift-card-activity-response.md | 2 +- doc/models/create-payment-request.md | 3 +- doc/models/create-payment-response.md | 2 +- doc/models/create-terminal-action-request.md | 2 +- doc/models/create-terminal-action-response.md | 2 +- doc/models/create-terminal-refund-request.md | 2 +- doc/models/device-metadata.md | 43 ++ doc/models/get-terminal-action-response.md | 2 +- doc/models/gift-card-activity-activate.md | 10 +- ...t-card-activity-adjust-decrement-reason.md | 2 + .../gift-card-activity-adjust-decrement.md | 4 +- ...t-card-activity-adjust-increment-reason.md | 4 +- .../gift-card-activity-adjust-increment.md | 4 +- doc/models/gift-card-activity-block-reason.md | 2 + doc/models/gift-card-activity-block.md | 4 +- ...gift-card-activity-clear-balance-reason.md | 2 + .../gift-card-activity-clear-balance.md | 4 +- .../gift-card-activity-deactivate-reason.md | 4 +- doc/models/gift-card-activity-deactivate.md | 4 +- .../gift-card-activity-import-reversal.md | 2 +- doc/models/gift-card-activity-import.md | 5 +- doc/models/gift-card-activity-load.md | 10 +- .../gift-card-activity-redeem-status.md | 19 + doc/models/gift-card-activity-redeem.md | 10 +- doc/models/gift-card-activity-refund.md | 10 +- doc/models/gift-card-activity-type.md | 26 +- .../gift-card-activity-unblock-reason.md | 2 + doc/models/gift-card-activity-unblock.md | 4 +- ...-card-activity-unlinked-activity-refund.md | 6 +- doc/models/gift-card-activity.md | 40 +- doc/models/list-catalog-request.md | 2 +- doc/models/payment-options.md | 2 +- doc/models/payment.md | 4 +- doc/models/payout.md | 2 +- doc/models/search-catalog-objects-request.md | 2 +- doc/models/subscription-phase.md | 7 +- doc/models/terminal-action-action-type.md | 1 + doc/models/terminal-action.md | 6 +- src/Apis/BaseApi.php | 2 +- src/Apis/CatalogApi.php | 4 +- src/Apis/GiftCardsApi.php | 2 +- src/Apis/LoyaltyApi.php | 6 +- src/Apis/TerminalApi.php | 3 +- src/ConfigurationDefaults.php | 2 +- src/Models/AppointmentSegment.php | 38 +- .../BatchRetrieveInventoryChangesRequest.php | 26 ++ .../BatchRetrieveInventoryCountsRequest.php | 26 ++ src/Models/CalculateLoyaltyPointsResponse.php | 2 + src/Models/CancelTerminalActionResponse.php | 2 + src/Models/Card.php | 29 ++ src/Models/CardCoBrand.php | 39 ++ src/Models/CreateGiftCardActivityRequest.php | 10 +- src/Models/CreateGiftCardActivityResponse.php | 10 +- src/Models/CreatePaymentRequest.php | 60 ++- src/Models/CreateTerminalActionRequest.php | 2 + src/Models/CreateTerminalActionResponse.php | 2 + src/Models/DeviceMetadata.php | 373 ++++++++++++++++++ src/Models/GetTerminalActionResponse.php | 2 + src/Models/GiftCardActivity.php | 89 +++-- src/Models/GiftCardActivityActivate.php | 62 ++- .../GiftCardActivityAdjustDecrement.php | 4 +- .../GiftCardActivityAdjustDecrementReason.php | 3 + .../GiftCardActivityAdjustIncrement.php | 4 +- .../GiftCardActivityAdjustIncrementReason.php | 5 +- src/Models/GiftCardActivityBlock.php | 4 +- src/Models/GiftCardActivityBlockReason.php | 3 + src/Models/GiftCardActivityClearBalance.php | 4 +- .../GiftCardActivityClearBalanceReason.php | 3 + src/Models/GiftCardActivityDeactivate.php | 4 +- .../GiftCardActivityDeactivateReason.php | 5 +- src/Models/GiftCardActivityImport.php | 5 +- src/Models/GiftCardActivityImportReversal.php | 2 +- src/Models/GiftCardActivityLoad.php | 68 +++- src/Models/GiftCardActivityRedeem.php | 61 ++- src/Models/GiftCardActivityRedeemStatus.php | 55 +++ src/Models/GiftCardActivityRefund.php | 79 ++-- src/Models/GiftCardActivityType.php | 48 ++- src/Models/GiftCardActivityUnblock.php | 4 +- src/Models/GiftCardActivityUnblockReason.php | 3 + ...GiftCardActivityUnlinkedActivityRefund.php | 19 +- src/Models/ListCatalogRequest.php | 8 +- src/Models/Payment.php | 12 +- src/Models/PaymentOptions.php | 18 +- src/Models/Payout.php | 4 +- src/Models/SearchCatalogObjectsRequest.php | 8 +- src/Models/SubscriptionPhase.php | 23 +- src/Models/TerminalAction.php | 29 ++ src/Models/TerminalActionActionType.php | 8 +- src/SquareClient.php | 2 +- 105 files changed, 1257 insertions(+), 368 deletions(-) create mode 100644 doc/models/card-co-brand.md create mode 100644 doc/models/device-metadata.md create mode 100644 doc/models/gift-card-activity-redeem-status.md create mode 100644 src/Models/CardCoBrand.php create mode 100644 src/Models/DeviceMetadata.php create mode 100644 src/Models/GiftCardActivityRedeemStatus.php diff --git a/CHANGELOG.md b/CHANGELOG.md index a11fad8c..034dc1e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ For general API and SDK changelogs, see [Square APIs and SDKs Release Notes](https://developer.squareup.com/docs/changelog/connect). +## Version 19.0.1.20220512 (2022-05-12) +- Fixed [Op Cache can break response types](https://github.com/square/square-php-sdk/issues/80) + ## Version 17.3.0.20220316 (2022-03-16) ### Added diff --git a/composer.json b/composer.json index f4580862..2963924e 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "square/square", "description": "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.", - "version": "19.0.1.20220512", + "version": "19.1.0.20220616", "type": "library", "keywords": [ "Square", @@ -23,7 +23,7 @@ "ext-json": "*", "ext-mbstring": "*", "apimatic/unirest-php": "^2.2.2", - "apimatic/jsonmapper": "^3.0.1" + "apimatic/jsonmapper": "^3.0.3" }, "require-dev": { "squizlabs/php_codesniffer": "^3.5", diff --git a/doc/apis/catalog.md b/doc/apis/catalog.md index caa52b66..d2eb8c71 100644 --- a/doc/apis/catalog.md +++ b/doc/apis/catalog.md @@ -405,7 +405,7 @@ function listCatalog(?string $cursor = null, ?string $types = null, ?int $catalo | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `?string` | Query, Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
The page size is currently set to be 100.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `types` | `?string` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
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. | +| `types` | `?string` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST,
PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | | `catalogVersion` | `?int` | Query, Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](../../doc/models/catalog-object.md)s' `version` attribute. If not included, results will
be from the current version of the catalog. | ## Response Type diff --git a/doc/apis/gift-cards.md b/doc/apis/gift-cards.md index 469f35fb..f9a3df6a 100644 --- a/doc/apis/gift-cards.md +++ b/doc/apis/gift-cards.md @@ -22,7 +22,7 @@ $giftCardsApi = $client->getGiftCardsApi(); # List Gift Cards Lists all gift cards. You can specify optional filters to retrieve -a subset of the gift cards. +a subset of the gift cards. Results are sorted by `created_at` in ascending order. ```php function listGiftCards( diff --git a/doc/apis/loyalty.md b/doc/apis/loyalty.md index 6bd290f6..fa3b52cc 100644 --- a/doc/apis/loyalty.md +++ b/doc/apis/loyalty.md @@ -161,7 +161,7 @@ if ($apiResponse->isSuccess()) { # Accumulate Loyalty Points -Adds points to a loyalty account. +Adds points earned from the base loyalty program to a loyalty account. - If you are using the Orders API to manage orders, you only provide the `order_id`. The endpoint reads the order to compute points to add to the buyer's account. @@ -171,6 +171,8 @@ Adds points to a loyalty account. [CalculateLoyaltyPoints](../../doc/apis/loyalty.md#calculate-loyalty-points) to compute the points that you provide to this endpoint. +This endpoint excludes additional points earned from loyalty promotions. + ```php function accumulateLoyaltyPoints(string $accountId, AccumulateLoyaltyPointsRequest $body): ApiResponse ``` @@ -392,7 +394,7 @@ if ($apiResponse->isSuccess()) { # Calculate Loyalty Points -Calculates the points a purchase earns. +Calculates the points a purchase earns from the base loyalty program. - If you are using the Orders API to manage orders, you provide the `order_id` in the request. The endpoint calculates the points by reading the order. diff --git a/doc/apis/terminal.md b/doc/apis/terminal.md index 9fa60e69..18d5dcf7 100644 --- a/doc/apis/terminal.md +++ b/doc/apis/terminal.md @@ -26,8 +26,7 @@ $terminalApi = $client->getTerminalApi(); # Create Terminal Action -Creates a Terminal action request and sends it to the specified device to take a payment -for the requested amount. +Creates a Terminal action request and sends it to the specified device. ```php function createTerminalAction(CreateTerminalActionRequest $body): ApiResponse diff --git a/doc/client.md b/doc/client.md index fad27587..768b54a8 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 | | --- | --- | --- | -| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2022-05-12'` | +| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2022-06-16'` | | `customUrl` | `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`** | | `timeout` | `int` | Timeout for API calls in seconds.
*Default*: `60` | @@ -27,7 +27,7 @@ The API client can be initialized as follows: $client = new Square\SquareClient([ // Set authentication parameters 'accessToken' => 'AccessToken', - 'squareVersion' => '2022-05-12', + 'squareVersion' => '2022-06-16', // Set the environment 'environment' => 'production', @@ -54,7 +54,7 @@ require_once "vendor/autoload.php"; $client = new Square\SquareClient([ 'accessToken' => 'AccessToken', - 'squareVersion' => '2022-05-12', + 'squareVersion' => '2022-06-16', ]); $locationsApi = $client->getLocationsApi(); diff --git a/doc/models/appointment-segment.md b/doc/models/appointment-segment.md index 98f05829..fd0c95aa 100644 --- a/doc/models/appointment-segment.md +++ b/doc/models/appointment-segment.md @@ -12,9 +12,9 @@ Defines an appointment segment of a booking. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `durationMinutes` | `?int` | Optional | The time span in minutes of an appointment segment.
**Constraints**: `<= 1500` | getDurationMinutes(): ?int | setDurationMinutes(?int durationMinutes): void | -| `serviceVariationId` | `string` | Required | The ID of the [CatalogItemVariation](../../doc/models/catalog-item-variation.md) object representing the service booked in this segment.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `36` | getServiceVariationId(): string | setServiceVariationId(string serviceVariationId): void | +| `serviceVariationId` | `?string` | Optional | The ID of the [CatalogItemVariation](../../doc/models/catalog-item-variation.md) object representing the service booked in this segment.
**Constraints**: *Maximum Length*: `36` | getServiceVariationId(): ?string | setServiceVariationId(?string serviceVariationId): void | | `teamMemberId` | `string` | Required | The ID of the [TeamMember](../../doc/models/team-member.md) object representing the team member booked in this segment.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `32` | getTeamMemberId(): string | setTeamMemberId(string teamMemberId): void | -| `serviceVariationVersion` | `int` | Required | The current version of the item variation representing the service booked in this segment. | getServiceVariationVersion(): int | setServiceVariationVersion(int serviceVariationVersion): void | +| `serviceVariationVersion` | `?int` | Optional | The current version of the item variation representing the service booked in this segment. | getServiceVariationVersion(): ?int | setServiceVariationVersion(?int serviceVariationVersion): void | | `intermissionMinutes` | `?int` | Optional | Time between the end of this segment and the beginning of the subsequent segment. | getIntermissionMinutes(): ?int | setIntermissionMinutes(?int intermissionMinutes): void | | `anyTeamMember` | `?bool` | Optional | Whether the customer accepts any team member, instead of a specific one, to serve this segment. | getAnyTeamMember(): ?bool | setAnyTeamMember(?bool anyTeamMember): void | | `resourceIds` | `?(string[])` | Optional | The IDs of the seller-accessible resources used for this appointment segment. | getResourceIds(): ?array | setResourceIds(?array resourceIds): void | @@ -24,9 +24,9 @@ Defines an appointment segment of a booking. ```json { "duration_minutes": null, - "service_variation_id": "service_variation_id6", + "service_variation_id": null, "team_member_id": "team_member_id0", - "service_variation_version": 56, + "service_variation_version": null, "intermission_minutes": null, "any_team_member": null, "resource_ids": null diff --git a/doc/models/batch-retrieve-inventory-changes-request.md b/doc/models/batch-retrieve-inventory-changes-request.md index 58ee954f..26d16c2c 100644 --- a/doc/models/batch-retrieve-inventory-changes-request.md +++ b/doc/models/batch-retrieve-inventory-changes-request.md @@ -13,9 +13,10 @@ | `locationIds` | `?(string[])` | Optional | The filter to return results by `Location` ID.
The filter is only applicable when set. The default value is null. | getLocationIds(): ?array | setLocationIds(?array locationIds): void | | `types` | [`?(string[]) (InventoryChangeType)`](../../doc/models/inventory-change-type.md) | Optional | The filter to return results by `InventoryChangeType` values other than `TRANSFER`.
The default value is `[PHYSICAL_COUNT, ADJUSTMENT]`. | getTypes(): ?array | setTypes(?array types): void | | `states` | [`?(string[]) (InventoryState)`](../../doc/models/inventory-state.md) | Optional | The filter to return `ADJUSTMENT` query results by
`InventoryState`. This filter is only applied when set.
The default value is null. | getStates(): ?array | setStates(?array states): void | -| `updatedAfter` | `?string` | Optional | The filter to return results with their `calculated_at` value
after the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | getUpdatedAfter(): ?string | setUpdatedAfter(?string updatedAfter): void | -| `updatedBefore` | `?string` | Optional | The filter to return results with their `created_at` or `calculated_at` value
strictly before the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | getUpdatedBefore(): ?string | setUpdatedBefore(?string updatedBefore): void | +| `updatedAfter` | `?string` | Optional | The filter to return results with their `calculated_at` value
after the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | getUpdatedAfter(): ?string | setUpdatedAfter(?string updatedAfter): void | +| `updatedBefore` | `?string` | Optional | The filter to return results with their `created_at` or `calculated_at` value
strictly before the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | getUpdatedBefore(): ?string | setUpdatedBefore(?string updatedBefore): void | | `cursor` | `?string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. | getCursor(): ?string | setCursor(?string cursor): void | +| `limit` | `?int` | Optional | **Constraints**: `>= 1`, `<= 1000` | getLimit(): ?int | setLimit(?int limit): void | ## Example (as JSON) diff --git a/doc/models/batch-retrieve-inventory-counts-request.md b/doc/models/batch-retrieve-inventory-counts-request.md index db042876..10caa4f8 100644 --- a/doc/models/batch-retrieve-inventory-counts-request.md +++ b/doc/models/batch-retrieve-inventory-counts-request.md @@ -14,6 +14,7 @@ | `updatedAfter` | `?string` | Optional | The filter to return results with their `calculated_at` value
after the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | getUpdatedAfter(): ?string | setUpdatedAfter(?string updatedAfter): void | | `cursor` | `?string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. | getCursor(): ?string | setCursor(?string cursor): void | | `states` | [`?(string[]) (InventoryState)`](../../doc/models/inventory-state.md) | Optional | The filter to return results by `InventoryState`. The filter is only applicable when set.
Ignored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`.
The default is null. | getStates(): ?array | setStates(?array states): void | +| `limit` | `?int` | Optional | **Constraints**: `>= 1`, `<= 1000` | getLimit(): ?int | setLimit(?int limit): void | ## Example (as JSON) diff --git a/doc/models/calculate-loyalty-points-response.md b/doc/models/calculate-loyalty-points-response.md index ebc7c9c6..d8776016 100644 --- a/doc/models/calculate-loyalty-points-response.md +++ b/doc/models/calculate-loyalty-points-response.md @@ -13,7 +13,7 @@ a specified purchase. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | getErrors(): ?array | setErrors(?array errors): void | -| `points` | `?int` | Optional | The points that the buyer can earn from a specified purchase. | getPoints(): ?int | setPoints(?int points): void | +| `points` | `?int` | Optional | The points that the buyer can earn from a specified purchase.
This value does not include additional points earned from a loyalty promotion. | getPoints(): ?int | setPoints(?int points): void | ## Example (as JSON) diff --git a/doc/models/cancel-terminal-action-response.md b/doc/models/cancel-terminal-action-response.md index e216cd4a..5ebfcde9 100644 --- a/doc/models/cancel-terminal-action-response.md +++ b/doc/models/cancel-terminal-action-response.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void | -| `action` | [`?TerminalAction`](../../doc/models/terminal-action.md) | Optional | - | getAction(): ?TerminalAction | setAction(?TerminalAction action): void | +| `action` | [`?TerminalAction`](../../doc/models/terminal-action.md) | Optional | Represents an action processed by the Square Terminal. | getAction(): ?TerminalAction | setAction(?TerminalAction action): void | ## Example (as JSON) diff --git a/doc/models/card-co-brand.md b/doc/models/card-co-brand.md new file mode 100644 index 00000000..8e5872da --- /dev/null +++ b/doc/models/card-co-brand.md @@ -0,0 +1,17 @@ + +# Card Co Brand + +Indicates the brand for a co-branded card. + +## Enumeration + +`CardCoBrand` + +## Fields + +| Name | +| --- | +| `UNKNOWN` | +| `AFTERPAY` | +| `CLEARPAY` | + diff --git a/doc/models/card.md b/doc/models/card.md index 85ae1d69..adc68d58 100644 --- a/doc/models/card.md +++ b/doc/models/card.md @@ -28,6 +28,7 @@ details are determined by the payment token generated by Web Payments SDK. | `prepaidType` | [`?string (CardPrepaidType)`](../../doc/models/card-prepaid-type.md) | Optional | Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`. | getPrepaidType(): ?string | setPrepaidType(?string prepaidType): void | | `bin` | `?string` | Optional | The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API
returns this field.
**Constraints**: *Maximum Length*: `6` | getBin(): ?string | setBin(?string bin): void | | `version` | `?int` | Optional | Current version number of the card. Increments with each card update. Requests to update an
existing Card object will be rejected unless the version in the request matches the current
version for the Card. | getVersion(): ?int | setVersion(?int version): void | +| `cardCoBrand` | [`?string (CardCoBrand)`](../../doc/models/card-co-brand.md) | Optional | Indicates the brand for a co-branded card. | getCardCoBrand(): ?string | setCardCoBrand(?string cardCoBrand): void | ## Example (as JSON) @@ -48,7 +49,8 @@ details are determined by the payment token generated by Web Payments SDK. "card_type": null, "prepaid_type": null, "bin": null, - "version": null + "version": null, + "card_co_brand": null } ``` diff --git a/doc/models/catalog-subscription-plan.md b/doc/models/catalog-subscription-plan.md index 95df31d7..8b3082d5 100644 --- a/doc/models/catalog-subscription-plan.md +++ b/doc/models/catalog-subscription-plan.md @@ -25,20 +25,14 @@ Describes a subscription plan. For more information, see "uid": null, "cadence": "EVERY_FOUR_MONTHS", "periods": null, - "recurring_price_money": { - "amount": null, - "currency": null - }, + "recurring_price_money": null, "ordinal": null }, { "uid": null, "cadence": "QUARTERLY", "periods": null, - "recurring_price_money": { - "amount": null, - "currency": null - }, + "recurring_price_money": null, "ordinal": null } ] diff --git a/doc/models/create-gift-card-activity-request.md b/doc/models/create-gift-card-activity-request.md index 1652a826..f943967e 100644 --- a/doc/models/create-gift-card-activity-request.md +++ b/doc/models/create-gift-card-activity-request.md @@ -12,7 +12,7 @@ A request to create a gift card activity. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `idempotencyKey` | `string` | Required | A unique string that identifies the `CreateGiftCardActivity` request.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `128` | getIdempotencyKey(): string | setIdempotencyKey(string idempotencyKey): void | -| `giftCardActivity` | [`GiftCardActivity`](../../doc/models/gift-card-activity.md) | Required | Represents an action performed on a gift card that affects its state or balance. | getGiftCardActivity(): GiftCardActivity | setGiftCardActivity(GiftCardActivity giftCardActivity): void | +| `giftCardActivity` | [`GiftCardActivity`](../../doc/models/gift-card-activity.md) | Required | Represents an action performed on a [gift card](../../doc/models/gift-card.md) that affects its state or balance.
A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity
includes a `redeem_activity_details` field that contains information about the redemption. | getGiftCardActivity(): GiftCardActivity | setGiftCardActivity(GiftCardActivity giftCardActivity): void | ## Example (as JSON) diff --git a/doc/models/create-gift-card-activity-response.md b/doc/models/create-gift-card-activity-response.md index 9f6b10fc..cbb4b887 100644 --- a/doc/models/create-gift-card-activity-response.md +++ b/doc/models/create-gift-card-activity-response.md @@ -13,7 +13,7 @@ The response might contain a set of `Error` objects if the request resulted in e | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | getErrors(): ?array | setErrors(?array errors): void | -| `giftCardActivity` | [`?GiftCardActivity`](../../doc/models/gift-card-activity.md) | Optional | Represents an action performed on a gift card that affects its state or balance. | getGiftCardActivity(): ?GiftCardActivity | setGiftCardActivity(?GiftCardActivity giftCardActivity): void | +| `giftCardActivity` | [`?GiftCardActivity`](../../doc/models/gift-card-activity.md) | Optional | Represents an action performed on a [gift card](../../doc/models/gift-card.md) that affects its state or balance.
A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity
includes a `redeem_activity_details` field that contains information about the redemption. | getGiftCardActivity(): ?GiftCardActivity | setGiftCardActivity(?GiftCardActivity giftCardActivity): void | ## Example (as JSON) diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index 29aadae3..fcf3ee16 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -17,7 +17,8 @@ Describes a request to create a payment using | `amountMoney` | [`Money`](../../doc/models/money.md) | Required | 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. | getAmountMoney(): Money | setAmountMoney(Money amountMoney): void | | `tipMoney` | [`?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. | getTipMoney(): ?Money | setTipMoney(?Money tipMoney): void | | `appFeeMoney` | [`?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. | getAppFeeMoney(): ?Money | setAppFeeMoney(?Money appFeeMoney): void | -| `delayDuration` | `?string` | Optional | The duration of time after the payment's creation when Square automatically cancels the
payment. This automatic cancellation applies only to payments that do not reach a terminal state
(COMPLETED, CANCELED, or FAILED) before the `delay_duration` time period.

This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value
of 1 minute.

Note: This feature is only supported for card payments. This parameter can only be set for a delayed
capture payment (`autocomplete=false`).

Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | getDelayDuration(): ?string | setDelayDuration(?string delayDuration): void | +| `delayDuration` | `?string` | Optional | The duration of time after the payment's creation when Square automatically
either completes or cancels the payment depending on the `delay_action` field value.
For more information, see
[Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

This parameter should be specified as a time duration, in RFC 3339 format.

Note: This feature is only supported for card payments. This parameter can only be set for a delayed
capture payment (`autocomplete=false`).

Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | getDelayDuration(): ?string | setDelayDuration(?string delayDuration): void | +| `delayAction` | `?string` | Optional | The action to be applied to the payment when the `delay_duration` has elapsed. The action must be
CANCEL or COMPLETE. For more information, see
[Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

Default: CANCEL | getDelayAction(): ?string | setDelayAction(?string delayAction): void | | `autocomplete` | `?bool` | Optional | If set to `true`, this payment will be completed when possible. If
set to `false`, this payment is held in an approved state until either
explicitly completed (captured) or canceled (voided). For more information, see
[Delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).

Default: true | getAutocomplete(): ?bool | setAutocomplete(?bool autocomplete): void | | `orderId` | `?string` | Optional | Associates a previously created order with this payment. | getOrderId(): ?string | setOrderId(?string orderId): void | | `customerId` | `?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. | getCustomerId(): ?string | setCustomerId(?string customerId): void | diff --git a/doc/models/create-payment-response.md b/doc/models/create-payment-response.md index ff835bdb..a7645166 100644 --- a/doc/models/create-payment-response.md +++ b/doc/models/create-payment-response.md @@ -70,7 +70,7 @@ present, or it might be present with a status of `FAILED`. "note": "Brief Description", "order_id": "pRsjRTgFWATl7so6DxdKBJa7ssbZY", "receipt_number": "R2B3", - "receipt_url": "https://squareupstaging.com/receipt/preview/R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY", + "receipt_url": "https://squareup.com/receipt/preview/EXAMPLE_RECEIPT_ID", "reference_id": "123456", "risk_evaluation": { "created_at": "2021-10-13T21:14:30.423Z", diff --git a/doc/models/create-terminal-action-request.md b/doc/models/create-terminal-action-request.md index ca734b94..ab27c589 100644 --- a/doc/models/create-terminal-action-request.md +++ b/doc/models/create-terminal-action-request.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `idempotencyKey` | `string` | Required | A unique string that identifies this `CreateAction` request. Keys can be any valid string
but must be unique for every `CreateAction` request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `64` | getIdempotencyKey(): string | setIdempotencyKey(string idempotencyKey): void | -| `action` | [`TerminalAction`](../../doc/models/terminal-action.md) | Required | - | getAction(): TerminalAction | setAction(TerminalAction action): void | +| `action` | [`TerminalAction`](../../doc/models/terminal-action.md) | Required | Represents an action processed by the Square Terminal. | getAction(): TerminalAction | setAction(TerminalAction action): void | ## Example (as JSON) diff --git a/doc/models/create-terminal-action-response.md b/doc/models/create-terminal-action-response.md index 2c988910..e75b70dd 100644 --- a/doc/models/create-terminal-action-response.md +++ b/doc/models/create-terminal-action-response.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void | -| `action` | [`?TerminalAction`](../../doc/models/terminal-action.md) | Optional | - | getAction(): ?TerminalAction | setAction(?TerminalAction action): void | +| `action` | [`?TerminalAction`](../../doc/models/terminal-action.md) | Optional | Represents an action processed by the Square Terminal. | getAction(): ?TerminalAction | setAction(?TerminalAction action): void | ## Example (as JSON) diff --git a/doc/models/create-terminal-refund-request.md b/doc/models/create-terminal-refund-request.md index ea3b63b8..9f483924 100644 --- a/doc/models/create-terminal-refund-request.md +++ b/doc/models/create-terminal-refund-request.md @@ -9,7 +9,7 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `idempotencyKey` | `string` | Required | A unique string that identifies this `CreateRefund` request. Keys can be any valid string but
must be unique for every `CreateRefund` request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1` | getIdempotencyKey(): string | setIdempotencyKey(string idempotencyKey): void | +| `idempotencyKey` | `string` | Required | A unique string that identifies this `CreateRefund` request. Keys can be any valid string but
must be unique for every `CreateRefund` request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `64` | getIdempotencyKey(): string | setIdempotencyKey(string idempotencyKey): void | | `refund` | [`?TerminalRefund`](../../doc/models/terminal-refund.md) | Optional | Represents a payment refund processed by the Square Terminal. Only supports Interac (Canadian debit network) payment refunds. | getRefund(): ?TerminalRefund | setRefund(?TerminalRefund refund): void | ## Example (as JSON) diff --git a/doc/models/device-metadata.md b/doc/models/device-metadata.md new file mode 100644 index 00000000..44406167 --- /dev/null +++ b/doc/models/device-metadata.md @@ -0,0 +1,43 @@ + +# Device Metadata + +## Structure + +`DeviceMetadata` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `batteryPercentage` | `?string` | Optional | The Terminal’s remaining battery percentage, between 1-100. | getBatteryPercentage(): ?string | setBatteryPercentage(?string batteryPercentage): void | +| `chargingState` | `?string` | Optional | The current charging state of the Terminal.
Options: `CHARGING`, `NOT_CHARGING` | getChargingState(): ?string | setChargingState(?string chargingState): void | +| `locationId` | `?string` | Optional | The ID of the Square seller business location associated with the Terminal. | getLocationId(): ?string | setLocationId(?string locationId): void | +| `merchantId` | `?string` | Optional | The ID of the Square merchant account that is currently signed-in to the Terminal. | getMerchantId(): ?string | setMerchantId(?string merchantId): void | +| `networkConnectionType` | `?string` | Optional | The Terminal’s current network connection type.
Options: `WIFI`, `ETHERNET` | getNetworkConnectionType(): ?string | setNetworkConnectionType(?string networkConnectionType): void | +| `paymentRegion` | `?string` | Optional | The country in which the Terminal is authorized to take payments. | getPaymentRegion(): ?string | setPaymentRegion(?string paymentRegion): void | +| `serialNumber` | `?string` | Optional | The unique identifier assigned to the Terminal, which can be found on the lower back
of the device. | getSerialNumber(): ?string | setSerialNumber(?string serialNumber): void | +| `osVersion` | `?string` | Optional | The current version of the Terminal’s operating system. | getOsVersion(): ?string | setOsVersion(?string osVersion): void | +| `appVersion` | `?string` | Optional | The current version of the application running on the Terminal. | getAppVersion(): ?string | setAppVersion(?string appVersion): void | +| `wifiNetworkName` | `?string` | Optional | The name of the Wi-Fi network to which the Terminal is connected. | getWifiNetworkName(): ?string | setWifiNetworkName(?string wifiNetworkName): void | +| `wifiNetworkStrength` | `?string` | Optional | The signal strength of the Wi-FI network connection.
Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT` | getWifiNetworkStrength(): ?string | setWifiNetworkStrength(?string wifiNetworkStrength): void | +| `ipAddress` | `?string` | Optional | The IP address of the Terminal. | getIpAddress(): ?string | setIpAddress(?string ipAddress): void | + +## Example (as JSON) + +```json +{ + "battery_percentage": null, + "charging_state": null, + "location_id": null, + "merchant_id": null, + "network_connection_type": null, + "payment_region": null, + "serial_number": null, + "os_version": null, + "app_version": null, + "wifi_network_name": null, + "wifi_network_strength": null, + "ip_address": null +} +``` + diff --git a/doc/models/get-terminal-action-response.md b/doc/models/get-terminal-action-response.md index 996ecfb8..687d3552 100644 --- a/doc/models/get-terminal-action-response.md +++ b/doc/models/get-terminal-action-response.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void | -| `action` | [`?TerminalAction`](../../doc/models/terminal-action.md) | Optional | - | getAction(): ?TerminalAction | setAction(?TerminalAction action): void | +| `action` | [`?TerminalAction`](../../doc/models/terminal-action.md) | Optional | Represents an action processed by the Square Terminal. | getAction(): ?TerminalAction | setAction(?TerminalAction action): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-activate.md b/doc/models/gift-card-activity-activate.md index fc47ba53..6f489fa6 100644 --- a/doc/models/gift-card-activity-activate.md +++ b/doc/models/gift-card-activity-activate.md @@ -1,7 +1,7 @@ # Gift Card Activity Activate -Describes a gift card activity of the ACTIVATE type. +Represents details about an `ACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,10 +12,10 @@ Describes a gift card activity of the ACTIVATE type. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `amountMoney` | [`?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. | getAmountMoney(): ?Money | setAmountMoney(?Money amountMoney): void | -| `orderId` | `?string` | Optional | The ID of the order associated with the activity.
This is required if your application uses the Square Orders API. | getOrderId(): ?string | setOrderId(?string orderId): void | -| `lineItemUid` | `?string` | Optional | The `line_item_uid` of the gift card line item in an order.
This is required if your application uses the Square Orders API. | getLineItemUid(): ?string | setLineItemUid(?string lineItemUid): void | -| `referenceId` | `?string` | Optional | If your application does not use the Square Orders API, you can optionally use this field
to associate the gift card activity with a client-side entity. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | -| `buyerPaymentInstrumentIds` | `?(string[])` | Optional | Required if your application does not use the Square Orders API.
This is a list of client-provided payment instrument IDs.
Square uses this information to perform compliance checks.
If you use the Square Orders API, Square has the necessary instrument IDs to perform necessary
compliance checks. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void | +| `orderId` | `?string` | Optional | The ID of the [order](../../doc/models/order.md) that contains the `GIFT_CARD` line item.

Applications that use the Square Orders API to process orders must specify the order ID
[CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) request. | getOrderId(): ?string | setOrderId(?string orderId): void | +| `lineItemUid` | `?string` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase.

Applications that use the Square Orders API to process orders must specify the line item UID
in the [CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) request. | getLineItemUid(): ?string | setLineItemUid(?string lineItemUid): void | +| `referenceId` | `?string` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom order processing system can use this field to track information
related to an order or payment. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | +| `buyerPaymentInstrumentIds` | `?(string[])` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-adjust-decrement-reason.md b/doc/models/gift-card-activity-adjust-decrement-reason.md index 9487073f..cc777eb5 100644 --- a/doc/models/gift-card-activity-adjust-decrement-reason.md +++ b/doc/models/gift-card-activity-adjust-decrement-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Adjust Decrement Reason +Indicates the reason for deducting money from a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityAdjustDecrementReason` diff --git a/doc/models/gift-card-activity-adjust-decrement.md b/doc/models/gift-card-activity-adjust-decrement.md index b2e35c59..645f2c78 100644 --- a/doc/models/gift-card-activity-adjust-decrement.md +++ b/doc/models/gift-card-activity-adjust-decrement.md @@ -1,7 +1,7 @@ # Gift Card Activity Adjust Decrement -Describes a gift card activity of the ADJUST_DECREMENT type. +Represents details about an `ADJUST_DECREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,7 +12,7 @@ Describes a gift card activity of the ADJUST_DECREMENT type. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `amountMoney` | [`Money`](../../doc/models/money.md) | Required | 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. | getAmountMoney(): Money | setAmountMoney(Money amountMoney): void | -| `reason` | [`string (GiftCardActivityAdjustDecrementReason)`](../../doc/models/gift-card-activity-adjust-decrement-reason.md) | Required | - | getReason(): string | setReason(string reason): void | +| `reason` | [`string (GiftCardActivityAdjustDecrementReason)`](../../doc/models/gift-card-activity-adjust-decrement-reason.md) | Required | Indicates the reason for deducting money from a [gift card](../../doc/models/gift-card.md). | getReason(): string | setReason(string reason): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-adjust-increment-reason.md b/doc/models/gift-card-activity-adjust-increment-reason.md index 9e39b65d..c7bebb4d 100644 --- a/doc/models/gift-card-activity-adjust-increment-reason.md +++ b/doc/models/gift-card-activity-adjust-increment-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Adjust Increment Reason +Indicates the reason for adding money to a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityAdjustIncrementReason` @@ -9,7 +11,7 @@ | Name | Description | | --- | --- | -| `COMPLIMENTARY` | Seller gifted a complimentary gift card balance increase. | +| `COMPLIMENTARY` | The seller gifted a complimentary gift card balance increase. | | `SUPPORT_ISSUE` | The seller increased the gift card balance
to accommodate support issues. | | `TRANSACTION_VOIDED` | The transaction is voided. | diff --git a/doc/models/gift-card-activity-adjust-increment.md b/doc/models/gift-card-activity-adjust-increment.md index c2c1c027..ee1ab536 100644 --- a/doc/models/gift-card-activity-adjust-increment.md +++ b/doc/models/gift-card-activity-adjust-increment.md @@ -1,7 +1,7 @@ # Gift Card Activity Adjust Increment -Describes a gift card activity of the ADJUST_INCREMENT type. +Represents details about an `ADJUST_INCREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,7 +12,7 @@ Describes a gift card activity of the ADJUST_INCREMENT type. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `amountMoney` | [`Money`](../../doc/models/money.md) | Required | 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. | getAmountMoney(): Money | setAmountMoney(Money amountMoney): void | -| `reason` | [`string (GiftCardActivityAdjustIncrementReason)`](../../doc/models/gift-card-activity-adjust-increment-reason.md) | Required | - | getReason(): string | setReason(string reason): void | +| `reason` | [`string (GiftCardActivityAdjustIncrementReason)`](../../doc/models/gift-card-activity-adjust-increment-reason.md) | Required | Indicates the reason for adding money to a [gift card](../../doc/models/gift-card.md). | getReason(): string | setReason(string reason): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-block-reason.md b/doc/models/gift-card-activity-block-reason.md index f1d82bf0..6bf54c74 100644 --- a/doc/models/gift-card-activity-block-reason.md +++ b/doc/models/gift-card-activity-block-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Block Reason +Indicates the reason for blocking a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityBlockReason` diff --git a/doc/models/gift-card-activity-block.md b/doc/models/gift-card-activity-block.md index 70916bbf..8745983c 100644 --- a/doc/models/gift-card-activity-block.md +++ b/doc/models/gift-card-activity-block.md @@ -1,7 +1,7 @@ # Gift Card Activity Block -Describes a gift card activity of the BLOCK type. +Represents details about a `BLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Describes a gift card activity of the BLOCK type. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_BLOCK'` | getReason(): string | setReason(string reason): void | +| `reason` | `string` | Required, Constant | Indicates the reason for blocking a [gift card](../../doc/models/gift-card.md).
**Default**: `'CHARGEBACK_BLOCK'` | getReason(): string | setReason(string reason): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-clear-balance-reason.md b/doc/models/gift-card-activity-clear-balance-reason.md index 39a15c31..9995993f 100644 --- a/doc/models/gift-card-activity-clear-balance-reason.md +++ b/doc/models/gift-card-activity-clear-balance-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Clear Balance Reason +Indicates the reason for clearing the balance of a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityClearBalanceReason` diff --git a/doc/models/gift-card-activity-clear-balance.md b/doc/models/gift-card-activity-clear-balance.md index 10fb5ac5..7f33743c 100644 --- a/doc/models/gift-card-activity-clear-balance.md +++ b/doc/models/gift-card-activity-clear-balance.md @@ -1,7 +1,7 @@ # Gift Card Activity Clear Balance -Describes a gift card activity of the CLEAR_BALANCE type. +Represents details about a `CLEAR_BALANCE` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Describes a gift card activity of the CLEAR_BALANCE type. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `reason` | [`string (GiftCardActivityClearBalanceReason)`](../../doc/models/gift-card-activity-clear-balance-reason.md) | Required | - | getReason(): string | setReason(string reason): void | +| `reason` | [`string (GiftCardActivityClearBalanceReason)`](../../doc/models/gift-card-activity-clear-balance-reason.md) | Required | Indicates the reason for clearing the balance of a [gift card](../../doc/models/gift-card.md). | getReason(): string | setReason(string reason): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-deactivate-reason.md b/doc/models/gift-card-activity-deactivate-reason.md index 491717ce..6797f7b5 100644 --- a/doc/models/gift-card-activity-deactivate-reason.md +++ b/doc/models/gift-card-activity-deactivate-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Deactivate Reason +Indicates the reason for deactivating a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityDeactivateReason` @@ -10,6 +12,6 @@ | Name | Description | | --- | --- | | `SUSPICIOUS_ACTIVITY` | The seller suspects suspicious activity. | -| `UNKNOWN_REASON` | The gift card deactivated for an unknown reason. | +| `UNKNOWN_REASON` | The gift card was deactivated for an unknown reason. | | `CHARGEBACK_DEACTIVATE` | A chargeback on the gift card purchase (or the gift card load) was ruled in favor of the buyer. | diff --git a/doc/models/gift-card-activity-deactivate.md b/doc/models/gift-card-activity-deactivate.md index 20a82926..086f0b56 100644 --- a/doc/models/gift-card-activity-deactivate.md +++ b/doc/models/gift-card-activity-deactivate.md @@ -1,7 +1,7 @@ # Gift Card Activity Deactivate -Describes a gift card activity of the DEACTIVATE type. +Represents details about a `DEACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Describes a gift card activity of the DEACTIVATE type. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `reason` | [`string (GiftCardActivityDeactivateReason)`](../../doc/models/gift-card-activity-deactivate-reason.md) | Required | - | getReason(): string | setReason(string reason): void | +| `reason` | [`string (GiftCardActivityDeactivateReason)`](../../doc/models/gift-card-activity-deactivate-reason.md) | Required | Indicates the reason for deactivating a [gift card](../../doc/models/gift-card.md). | getReason(): string | setReason(string reason): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-import-reversal.md b/doc/models/gift-card-activity-import-reversal.md index 3d04cd6f..ec32bf06 100644 --- a/doc/models/gift-card-activity-import-reversal.md +++ b/doc/models/gift-card-activity-import-reversal.md @@ -1,7 +1,7 @@ # Gift Card Activity Import Reversal -Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER +Represents details about an `IMPORT_REVERSAL` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure diff --git a/doc/models/gift-card-activity-import.md b/doc/models/gift-card-activity-import.md index 6036f1ce..0ce55982 100644 --- a/doc/models/gift-card-activity-import.md +++ b/doc/models/gift-card-activity-import.md @@ -1,8 +1,9 @@ # Gift Card Activity Import -Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER -(a third-party gift card). +Represents details about an `IMPORT` [gift card activity type](../../doc/models/gift-card-activity-type.md). +This activity type is used when Square imports a third-party gift card, in which case the +`gan_source` of the gift card is set to `OTHER`. ## Structure diff --git a/doc/models/gift-card-activity-load.md b/doc/models/gift-card-activity-load.md index 7cface65..c496f493 100644 --- a/doc/models/gift-card-activity-load.md +++ b/doc/models/gift-card-activity-load.md @@ -1,7 +1,7 @@ # Gift Card Activity Load -Present only when `GiftCardActivityType` is LOAD. +Represents details about a `LOAD` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,10 +12,10 @@ Present only when `GiftCardActivityType` is LOAD. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `amountMoney` | [`?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. | getAmountMoney(): ?Money | setAmountMoney(?Money amountMoney): void | -| `orderId` | `?string` | Optional | The `order_id` of the order associated with the activity.
It is populated along with `line_item_uid` and is required if using the Square Orders API. | getOrderId(): ?string | setOrderId(?string orderId): void | -| `lineItemUid` | `?string` | Optional | The `line_item_uid` of the gift card’s line item in the order associated with the activity.
It is populated along with `order_id` and is required if using the Square Orders API. | getLineItemUid(): ?string | setLineItemUid(?string lineItemUid): void | -| `referenceId` | `?string` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Orders
API is not being used. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | -| `buyerPaymentInstrumentIds` | `?(string[])` | Optional | If you are not using the Orders API, this field is required because it is used to identify a buyer
to perform compliance checks. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void | +| `orderId` | `?string` | Optional | The ID of the [order](../../doc/models/order.md) that contains the `GIFT_CARD` line item.

Applications that use the Square Orders API to process orders must specify the order ID in the
[CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) request. | getOrderId(): ?string | setOrderId(?string orderId): void | +| `lineItemUid` | `?string` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card.

Applications that use the Square Orders API to process orders must specify the line item UID
in the [CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) request. | getLineItemUid(): ?string | setLineItemUid(?string lineItemUid): void | +| `referenceId` | `?string` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom order processing system can use this field to track information related to
an order or payment. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | +| `buyerPaymentInstrumentIds` | `?(string[])` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-redeem-status.md b/doc/models/gift-card-activity-redeem-status.md new file mode 100644 index 00000000..ea411fbe --- /dev/null +++ b/doc/models/gift-card-activity-redeem-status.md @@ -0,0 +1,19 @@ + +# Gift Card Activity Redeem Status + +Indicates the status of a [gift card](../../doc/models/gift-card.md) redemption. This status is relevant only for +redemptions made from Square products (such as Square Point of Sale) because Square products use a +two-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` status. + +## Enumeration + +`GiftCardActivityRedeemStatus` + +## Fields + +| Name | Description | +| --- | --- | +| `PENDING` | The gift card redemption is pending. `PENDING` is a temporary status that applies when a
gift card is redeemed from Square Point of Sale or another Square product. A `PENDING` status is updated to
`COMPLETED` if the payment is captured or `CANCELED` if the authorization is voided. | +| `COMPLETED` | The gift card redemption is completed. | +| `CANCELED` | The gift card redemption is canceled. A redemption is canceled if the authorization
on the gift card is voided. | + diff --git a/doc/models/gift-card-activity-redeem.md b/doc/models/gift-card-activity-redeem.md index c5644998..6b98f9cd 100644 --- a/doc/models/gift-card-activity-redeem.md +++ b/doc/models/gift-card-activity-redeem.md @@ -1,7 +1,7 @@ # Gift Card Activity Redeem -Present only when `GiftCardActivityType` is REDEEM. +Represents details about a `REDEEM` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,8 +12,9 @@ Present only when `GiftCardActivityType` is REDEEM. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `amountMoney` | [`Money`](../../doc/models/money.md) | Required | 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. | getAmountMoney(): Money | setAmountMoney(Money amountMoney): void | -| `paymentId` | `?string` | Optional | When the Square Payments API is used, Redeem is not called on the Gift Cards API.
However, when Square reads a Redeem activity from the Gift Cards API, developers need to know the
associated `payment_id`. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | -| `referenceId` | `?string` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Orders
API is not being used. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | +| `paymentId` | `?string` | Optional | The ID of the payment that represents the gift card redemption. Square populates this field
if the payment was processed by Square. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | +| `referenceId` | `?string` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom payment processing system can use this field to track information
related to an order or payment. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | +| `status` | [`?string (GiftCardActivityRedeemStatus)`](../../doc/models/gift-card-activity-redeem-status.md) | Optional | Indicates the status of a [gift card](../../doc/models/gift-card.md) redemption. This status is relevant only for
redemptions made from Square products (such as Square Point of Sale) because Square products use a
two-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` status. | getStatus(): ?string | setStatus(?string status): void | ## Example (as JSON) @@ -24,7 +25,8 @@ Present only when `GiftCardActivityType` is REDEEM. "currency": null }, "payment_id": null, - "reference_id": null + "reference_id": null, + "status": null } ``` diff --git a/doc/models/gift-card-activity-refund.md b/doc/models/gift-card-activity-refund.md index 6df4b8fa..161517f7 100644 --- a/doc/models/gift-card-activity-refund.md +++ b/doc/models/gift-card-activity-refund.md @@ -1,7 +1,7 @@ # Gift Card Activity Refund -Present only when `GiftCardActivityType` is REFUND. +Represents details about a `REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,16 +11,16 @@ Present only when `GiftCardActivityType` is REFUND. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `redeemActivityId` | `string` | Required | The ID for the Redeem activity that needs to be refunded. Hence, the activity it
refers to has to be of the REDEEM type. | getRedeemActivityId(): string | setRedeemActivityId(string redeemActivityId): void | +| `redeemActivityId` | `?string` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the
`payment_id` in the corresponding [RefundPayment](../../doc/apis/refunds.md#refund-payment) request
represents a redemption made by the same gift card.

Applications that use a custom payment processing system can use this field in a
[CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity)
request to link a refund with a `REDEEM` activity for the same gift card. | getRedeemActivityId(): ?string | setRedeemActivityId(?string redeemActivityId): void | | `amountMoney` | [`?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. | getAmountMoney(): ?Money | setAmountMoney(?Money amountMoney): void | -| `referenceId` | `?string` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Orders
API is not being used. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | -| `paymentId` | `?string` | Optional | When the Square Payments API is used, Refund is not called on the Gift Cards API.
However, when Square reads a Refund activity from the Gift Cards API, the developer needs to know the
ID of the payment (made using this gift card) that is being refunded. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | +| `referenceId` | `?string` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom payment processing system can use this field to track information
related to an order or payment. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | +| `paymentId` | `?string` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a
payment processed by Square. The payment source can be the same gift card or a cross-tender payment from a
credit card or a different gift card. Cross-tender payments can only be refunded from Square Point of Sale
or other Square products. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | ## Example (as JSON) ```json { - "redeem_activity_id": "redeem_activity_id0", + "redeem_activity_id": null, "amount_money": null, "reference_id": null, "payment_id": null diff --git a/doc/models/gift-card-activity-type.md b/doc/models/gift-card-activity-type.md index fc5a5b53..e1caba82 100644 --- a/doc/models/gift-card-activity-type.md +++ b/doc/models/gift-card-activity-type.md @@ -1,7 +1,7 @@ # Gift Card Activity Type -Indicates the gift card activity type. +Indicates the type of [gift card activity](../../doc/models/gift-card-activity.md). ## Enumeration @@ -11,17 +11,17 @@ Indicates the gift card activity type. | Name | Description | | --- | --- | -| `ACTIVATE` | Activated a gift card with a balance. | +| `ACTIVATE` | Activated a gift card with a balance. When a gift card is activated, Square changes
the gift card state from `PENDING` to `ACTIVE`. A gift card must be in the `ACTIVE` state
to be used for other balance-changing activities. | | `LOAD` | Loaded a gift card with additional funds. | -| `REDEEM` | Redeemed a gift card. | -| `CLEAR_BALANCE` | Cleared a gift card balance to zero. | -| `DEACTIVATE` | Permanently blocked a gift card from a balance-changing
activity. | -| `ADJUST_INCREMENT` | Manually increased a gift card balance. | -| `ADJUST_DECREMENT` | Manually decreased a gift card balance. | -| `REFUND` | Added money to a gift card because a transaction
paid with this gift card was refunded. | -| `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card because a transaction
not linked to this gift card was refunded
to this gift card. | -| `IMPORT` | Imported a third-party gift card. | -| `BLOCK` | Temporarily blocked a gift card from balance-changing
activities. | -| `UNBLOCK` | Unblocked a gift card. It can resume balance-changing activities. | -| `IMPORT_REVERSAL` | A third-party gift card was imported with a balance.
The import is reversed. | +| `REDEEM` | Redeemed a gift card for a purchase. | +| `CLEAR_BALANCE` | Set the balance of a gift card to zero. | +| `DEACTIVATE` | Permanently blocked a gift card from balance-changing activities. | +| `ADJUST_INCREMENT` | Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow. | +| `ADJUST_DECREMENT` | Deducted money from a gift card outside of a typical `REDEEM` activity flow. | +| `REFUND` | Added money to a gift card from a refunded transaction. The refund might be linked to
a Square payment, depending on how the payment and refund are processed. For example:

- A gift card payment processed by Square can be refunded to the same gift card.
- A cross-tender payment processed by Square can be refunded to a gift card. The cross-tender
payment source can be a credit card or different gift card.
- A payment processed with a custom processing system (instead of the Square Payments API) can
be refunded to a gift card. | +| `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card from a refunded transaction that is not linked to the gift card.

This activity type is included for backward compatibility and should not be used to create a refund.
Instead, use the `REFUND` activity type. | +| `IMPORT` | Imported a third-party gift card with a balance. `IMPORT` activities are managed
by Square and cannot be created using the Gift Card Activities API. | +| `BLOCK` | Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities
are managed by Square and cannot be created using the Gift Card Activities API. | +| `UNBLOCK` | Unblocked a gift card, which enables it to resume balance-changing activities. `UNBLOCK`
activities are managed by Square and cannot be created using the Gift Card Activities API. | +| `IMPORT_REVERSAL` | Reversed the import of a third-party gift card, which sets the gift card state to
`PENDING` and clears the balance. `IMPORT_REVERSAL` activities are managed by Square and
cannot be created using the Gift Card Activities API. | diff --git a/doc/models/gift-card-activity-unblock-reason.md b/doc/models/gift-card-activity-unblock-reason.md index 40304220..11ccbda8 100644 --- a/doc/models/gift-card-activity-unblock-reason.md +++ b/doc/models/gift-card-activity-unblock-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Unblock Reason +Indicates the reason for unblocking a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityUnblockReason` diff --git a/doc/models/gift-card-activity-unblock.md b/doc/models/gift-card-activity-unblock.md index a83fef86..dd6dfa73 100644 --- a/doc/models/gift-card-activity-unblock.md +++ b/doc/models/gift-card-activity-unblock.md @@ -1,7 +1,7 @@ # Gift Card Activity Unblock -Present only when `GiftCardActivityType` is UNBLOCK. +Represents details about an `UNBLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Present only when `GiftCardActivityType` is UNBLOCK. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_UNBLOCK'` | getReason(): string | setReason(string reason): void | +| `reason` | `string` | Required, Constant | Indicates the reason for unblocking a [gift card](../../doc/models/gift-card.md).
**Default**: `'CHARGEBACK_UNBLOCK'` | getReason(): string | setReason(string reason): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-unlinked-activity-refund.md b/doc/models/gift-card-activity-unlinked-activity-refund.md index 70d11a0a..c215b50b 100644 --- a/doc/models/gift-card-activity-unlinked-activity-refund.md +++ b/doc/models/gift-card-activity-unlinked-activity-refund.md @@ -1,7 +1,7 @@ # Gift Card Activity Unlinked Activity Refund -Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. +Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,8 +12,8 @@ Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `amountMoney` | [`Money`](../../doc/models/money.md) | Required | 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. | getAmountMoney(): Money | setAmountMoney(Money amountMoney): void | -| `referenceId` | `?string` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Payments
API is not being used. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | -| `paymentId` | `?string` | Optional | When using the Square Payments API, the ID of the payment that was refunded to this gift
card. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | +| `referenceId` | `?string` | Optional | A client-specified ID that associates the gift card activity with an entity in another system. | getReferenceId(): ?string | setReferenceId(?string referenceId): void | +| `paymentId` | `?string` | Optional | The ID of the refunded payment. This field is not used starting in Square version 2022-06-16. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity.md b/doc/models/gift-card-activity.md index 09660155..feed1b48 100644 --- a/doc/models/gift-card-activity.md +++ b/doc/models/gift-card-activity.md @@ -1,7 +1,9 @@ # Gift Card Activity -Represents an action performed on a gift card that affects its state or balance. +Represents an action performed on a [gift card](../../doc/models/gift-card.md) that affects its state or balance. +A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity +includes a `redeem_activity_details` field that contains information about the redemption. ## Structure @@ -11,26 +13,26 @@ Represents an action performed on a gift card that affects its state or balance. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `id` | `?string` | Optional | The unique ID of the gift card activity. | getId(): ?string | setId(?string id): void | -| `type` | [`string (GiftCardActivityType)`](../../doc/models/gift-card-activity-type.md) | Required | Indicates the gift card activity type. | getType(): string | setType(string type): void | -| `locationId` | `string` | Required | The ID of the location at which the activity occurred. | getLocationId(): string | setLocationId(string locationId): void | +| `id` | `?string` | Optional | The Square-assigned ID of the gift card activity. | getId(): ?string | setId(?string id): void | +| `type` | [`string (GiftCardActivityType)`](../../doc/models/gift-card-activity-type.md) | Required | Indicates the type of [gift card activity](../../doc/models/gift-card-activity.md). | getType(): string | setType(string type): void | +| `locationId` | `string` | Required | The ID of the [business location](../../doc/models/location.md) where the activity occurred. | getLocationId(): string | setLocationId(string locationId): void | | `createdAt` | `?string` | Optional | The timestamp when the gift card activity was created, in RFC 3339 format. | getCreatedAt(): ?string | setCreatedAt(?string createdAt): void | -| `giftCardId` | `?string` | Optional | The gift card ID. The ID is not required if a GAN is present. | getGiftCardId(): ?string | setGiftCardId(?string giftCardId): void | -| `giftCardGan` | `?string` | Optional | The gift card GAN. The GAN is not required if `gift_card_id` is present. | getGiftCardGan(): ?string | setGiftCardGan(?string giftCardGan): void | +| `giftCardId` | `?string` | Optional | The gift card ID. When creating a gift card activity, `gift_card_id` is not required if
`gift_card_gan` is specified. | getGiftCardId(): ?string | setGiftCardId(?string giftCardId): void | +| `giftCardGan` | `?string` | Optional | The gift card account number (GAN). When creating a gift card activity, `gift_card_gan`
is not required if `gift_card_id` is specified. | getGiftCardGan(): ?string | setGiftCardGan(?string giftCardGan): void | | `giftCardBalanceMoney` | [`?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. | getGiftCardBalanceMoney(): ?Money | setGiftCardBalanceMoney(?Money giftCardBalanceMoney): void | -| `loadActivityDetails` | [`?GiftCardActivityLoad`](../../doc/models/gift-card-activity-load.md) | Optional | Present only when `GiftCardActivityType` is LOAD. | getLoadActivityDetails(): ?GiftCardActivityLoad | setLoadActivityDetails(?GiftCardActivityLoad loadActivityDetails): void | -| `activateActivityDetails` | [`?GiftCardActivityActivate`](../../doc/models/gift-card-activity-activate.md) | Optional | Describes a gift card activity of the ACTIVATE type. | getActivateActivityDetails(): ?GiftCardActivityActivate | setActivateActivityDetails(?GiftCardActivityActivate activateActivityDetails): void | -| `redeemActivityDetails` | [`?GiftCardActivityRedeem`](../../doc/models/gift-card-activity-redeem.md) | Optional | Present only when `GiftCardActivityType` is REDEEM. | getRedeemActivityDetails(): ?GiftCardActivityRedeem | setRedeemActivityDetails(?GiftCardActivityRedeem redeemActivityDetails): void | -| `clearBalanceActivityDetails` | [`?GiftCardActivityClearBalance`](../../doc/models/gift-card-activity-clear-balance.md) | Optional | Describes a gift card activity of the CLEAR_BALANCE type. | getClearBalanceActivityDetails(): ?GiftCardActivityClearBalance | setClearBalanceActivityDetails(?GiftCardActivityClearBalance clearBalanceActivityDetails): void | -| `deactivateActivityDetails` | [`?GiftCardActivityDeactivate`](../../doc/models/gift-card-activity-deactivate.md) | Optional | Describes a gift card activity of the DEACTIVATE type. | getDeactivateActivityDetails(): ?GiftCardActivityDeactivate | setDeactivateActivityDetails(?GiftCardActivityDeactivate deactivateActivityDetails): void | -| `adjustIncrementActivityDetails` | [`?GiftCardActivityAdjustIncrement`](../../doc/models/gift-card-activity-adjust-increment.md) | Optional | Describes a gift card activity of the ADJUST_INCREMENT type. | getAdjustIncrementActivityDetails(): ?GiftCardActivityAdjustIncrement | setAdjustIncrementActivityDetails(?GiftCardActivityAdjustIncrement adjustIncrementActivityDetails): void | -| `adjustDecrementActivityDetails` | [`?GiftCardActivityAdjustDecrement`](../../doc/models/gift-card-activity-adjust-decrement.md) | Optional | Describes a gift card activity of the ADJUST_DECREMENT type. | getAdjustDecrementActivityDetails(): ?GiftCardActivityAdjustDecrement | setAdjustDecrementActivityDetails(?GiftCardActivityAdjustDecrement adjustDecrementActivityDetails): void | -| `refundActivityDetails` | [`?GiftCardActivityRefund`](../../doc/models/gift-card-activity-refund.md) | Optional | Present only when `GiftCardActivityType` is REFUND. | getRefundActivityDetails(): ?GiftCardActivityRefund | setRefundActivityDetails(?GiftCardActivityRefund refundActivityDetails): void | -| `unlinkedActivityRefundActivityDetails` | [`?GiftCardActivityUnlinkedActivityRefund`](../../doc/models/gift-card-activity-unlinked-activity-refund.md) | Optional | Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. | getUnlinkedActivityRefundActivityDetails(): ?GiftCardActivityUnlinkedActivityRefund | setUnlinkedActivityRefundActivityDetails(?GiftCardActivityUnlinkedActivityRefund unlinkedActivityRefundActivityDetails): void | -| `importActivityDetails` | [`?GiftCardActivityImport`](../../doc/models/gift-card-activity-import.md) | Optional | Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER
(a third-party gift card). | getImportActivityDetails(): ?GiftCardActivityImport | setImportActivityDetails(?GiftCardActivityImport importActivityDetails): void | -| `blockActivityDetails` | [`?GiftCardActivityBlock`](../../doc/models/gift-card-activity-block.md) | Optional | Describes a gift card activity of the BLOCK type. | getBlockActivityDetails(): ?GiftCardActivityBlock | setBlockActivityDetails(?GiftCardActivityBlock blockActivityDetails): void | -| `unblockActivityDetails` | [`?GiftCardActivityUnblock`](../../doc/models/gift-card-activity-unblock.md) | Optional | Present only when `GiftCardActivityType` is UNBLOCK. | getUnblockActivityDetails(): ?GiftCardActivityUnblock | setUnblockActivityDetails(?GiftCardActivityUnblock unblockActivityDetails): void | -| `importReversalActivityDetails` | [`?GiftCardActivityImportReversal`](../../doc/models/gift-card-activity-import-reversal.md) | Optional | Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER | getImportReversalActivityDetails(): ?GiftCardActivityImportReversal | setImportReversalActivityDetails(?GiftCardActivityImportReversal importReversalActivityDetails): void | +| `loadActivityDetails` | [`?GiftCardActivityLoad`](../../doc/models/gift-card-activity-load.md) | Optional | Represents details about a `LOAD` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getLoadActivityDetails(): ?GiftCardActivityLoad | setLoadActivityDetails(?GiftCardActivityLoad loadActivityDetails): void | +| `activateActivityDetails` | [`?GiftCardActivityActivate`](../../doc/models/gift-card-activity-activate.md) | Optional | Represents details about an `ACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getActivateActivityDetails(): ?GiftCardActivityActivate | setActivateActivityDetails(?GiftCardActivityActivate activateActivityDetails): void | +| `redeemActivityDetails` | [`?GiftCardActivityRedeem`](../../doc/models/gift-card-activity-redeem.md) | Optional | Represents details about a `REDEEM` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getRedeemActivityDetails(): ?GiftCardActivityRedeem | setRedeemActivityDetails(?GiftCardActivityRedeem redeemActivityDetails): void | +| `clearBalanceActivityDetails` | [`?GiftCardActivityClearBalance`](../../doc/models/gift-card-activity-clear-balance.md) | Optional | Represents details about a `CLEAR_BALANCE` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getClearBalanceActivityDetails(): ?GiftCardActivityClearBalance | setClearBalanceActivityDetails(?GiftCardActivityClearBalance clearBalanceActivityDetails): void | +| `deactivateActivityDetails` | [`?GiftCardActivityDeactivate`](../../doc/models/gift-card-activity-deactivate.md) | Optional | Represents details about a `DEACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getDeactivateActivityDetails(): ?GiftCardActivityDeactivate | setDeactivateActivityDetails(?GiftCardActivityDeactivate deactivateActivityDetails): void | +| `adjustIncrementActivityDetails` | [`?GiftCardActivityAdjustIncrement`](../../doc/models/gift-card-activity-adjust-increment.md) | Optional | Represents details about an `ADJUST_INCREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getAdjustIncrementActivityDetails(): ?GiftCardActivityAdjustIncrement | setAdjustIncrementActivityDetails(?GiftCardActivityAdjustIncrement adjustIncrementActivityDetails): void | +| `adjustDecrementActivityDetails` | [`?GiftCardActivityAdjustDecrement`](../../doc/models/gift-card-activity-adjust-decrement.md) | Optional | Represents details about an `ADJUST_DECREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getAdjustDecrementActivityDetails(): ?GiftCardActivityAdjustDecrement | setAdjustDecrementActivityDetails(?GiftCardActivityAdjustDecrement adjustDecrementActivityDetails): void | +| `refundActivityDetails` | [`?GiftCardActivityRefund`](../../doc/models/gift-card-activity-refund.md) | Optional | Represents details about a `REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getRefundActivityDetails(): ?GiftCardActivityRefund | setRefundActivityDetails(?GiftCardActivityRefund refundActivityDetails): void | +| `unlinkedActivityRefundActivityDetails` | [`?GiftCardActivityUnlinkedActivityRefund`](../../doc/models/gift-card-activity-unlinked-activity-refund.md) | Optional | Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getUnlinkedActivityRefundActivityDetails(): ?GiftCardActivityUnlinkedActivityRefund | setUnlinkedActivityRefundActivityDetails(?GiftCardActivityUnlinkedActivityRefund unlinkedActivityRefundActivityDetails): void | +| `importActivityDetails` | [`?GiftCardActivityImport`](../../doc/models/gift-card-activity-import.md) | Optional | Represents details about an `IMPORT` [gift card activity type](../../doc/models/gift-card-activity-type.md).
This activity type is used when Square imports a third-party gift card, in which case the
`gan_source` of the gift card is set to `OTHER`. | getImportActivityDetails(): ?GiftCardActivityImport | setImportActivityDetails(?GiftCardActivityImport importActivityDetails): void | +| `blockActivityDetails` | [`?GiftCardActivityBlock`](../../doc/models/gift-card-activity-block.md) | Optional | Represents details about a `BLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getBlockActivityDetails(): ?GiftCardActivityBlock | setBlockActivityDetails(?GiftCardActivityBlock blockActivityDetails): void | +| `unblockActivityDetails` | [`?GiftCardActivityUnblock`](../../doc/models/gift-card-activity-unblock.md) | Optional | Represents details about an `UNBLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getUnblockActivityDetails(): ?GiftCardActivityUnblock | setUnblockActivityDetails(?GiftCardActivityUnblock unblockActivityDetails): void | +| `importReversalActivityDetails` | [`?GiftCardActivityImportReversal`](../../doc/models/gift-card-activity-import-reversal.md) | Optional | Represents details about an `IMPORT_REVERSAL` [gift card activity type](../../doc/models/gift-card-activity-type.md). | getImportReversalActivityDetails(): ?GiftCardActivityImportReversal | setImportReversalActivityDetails(?GiftCardActivityImportReversal importReversalActivityDetails): void | ## Example (as JSON) diff --git a/doc/models/list-catalog-request.md b/doc/models/list-catalog-request.md index 24284e8a..d2fe1580 100644 --- a/doc/models/list-catalog-request.md +++ b/doc/models/list-catalog-request.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `cursor` | `?string` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
The page size is currently set to be 100.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | getCursor(): ?string | setCursor(?string cursor): void | -| `types` | `?string` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
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. | getTypes(): ?string | setTypes(?string types): void | +| `types` | `?string` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST,
PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | getTypes(): ?string | setTypes(?string types): void | | `catalogVersion` | `?int` | Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](../../doc/models/catalog-object.md)s' `version` attribute. If not included, results will
be from the current version of the catalog. | getCatalogVersion(): ?int | setCatalogVersion(?int catalogVersion): void | ## Example (as JSON) diff --git a/doc/models/payment-options.md b/doc/models/payment-options.md index 1e779d87..2de656c1 100644 --- a/doc/models/payment-options.md +++ b/doc/models/payment-options.md @@ -11,7 +11,7 @@ | --- | --- | --- | --- | --- | --- | | `autocomplete` | `?bool` | Optional | Indicates whether the `Payment` objects created from this `TerminalCheckout` are automatically
`COMPLETED` or left in an `APPROVED` state for later modification. | getAutocomplete(): ?bool | setAutocomplete(?bool autocomplete): void | | `delayDuration` | `?string` | Optional | The duration of time after the payment's creation when Square automatically cancels the
payment. This automatic cancellation applies only to payments that do not reach a terminal state
(COMPLETED, CANCELED, or FAILED) before the `delay_duration` time period.

This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value
of 1 minute.

Note: This feature is only supported for card payments. This parameter can only be set for a delayed
capture payment (`autocomplete=false`).
Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | getDelayDuration(): ?string | setDelayDuration(?string delayDuration): void | -| `acceptPartialAuthorization` | `?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 | getAcceptPartialAuthorization(): ?bool | setAcceptPartialAuthorization(?bool acceptPartialAuthorization): void | +| `acceptPartialAuthorization` | `?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`.
This field cannot be `true` when an `order_id` isn't specified.

For more information, see
[Take Partial Payments](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/partial-payments-with-gift-cards).

Default: false | getAcceptPartialAuthorization(): ?bool | setAcceptPartialAuthorization(?bool acceptPartialAuthorization): void | ## Example (as JSON) diff --git a/doc/models/payment.md b/doc/models/payment.md index a827dc70..97480928 100644 --- a/doc/models/payment.md +++ b/doc/models/payment.md @@ -23,7 +23,7 @@ Represents a payment processed by the Square API. | `refundedMoney` | [`?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. | getRefundedMoney(): ?Money | setRefundedMoney(?Money refundedMoney): void | | `status` | `?string` | Optional | Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.
**Constraints**: *Maximum Length*: `50` | getStatus(): ?string | setStatus(?string status): void | | `delayDuration` | `?string` | Optional | The duration of time after the payment's creation when Square automatically applies the
`delay_action` to the payment. This automatic `delay_action` applies only to payments that
do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the `delay_duration`
time period.

This field is specified as a time duration, in RFC 3339 format.

Notes:
This feature is only supported for card payments.

Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | getDelayDuration(): ?string | setDelayDuration(?string delayDuration): void | -| `delayAction` | `?string` | Optional | The action to be applied to the payment when the `delay_duration` has elapsed. This field
is read-only.

Current values include `CANCEL`. | getDelayAction(): ?string | setDelayAction(?string delayAction): void | +| `delayAction` | `?string` | Optional | The action to be applied to the payment when the `delay_duration` has elapsed.

Current values include `CANCEL` and `COMPLETE`. | getDelayAction(): ?string | setDelayAction(?string delayAction): void | | `delayedUntil` | `?string` | Optional | The read-only timestamp of when the `delay_action` is automatically applied,
in RFC 3339 format.

Note that this field is calculated by summing the payment's `delay_duration` and `created_at`
fields. The `created_at` field is generated by Square and might not exactly match the
time on your local machine. | getDelayedUntil(): ?string | setDelayedUntil(?string delayedUntil): void | | `sourceType` | `?string` | Optional | The source type for this payment.

Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `CASH`, or
`EXTERNAL`. For information about these payment source types,
see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).
**Constraints**: *Maximum Length*: `50` | getSourceType(): ?string | setSourceType(?string sourceType): void | | `cardDetails` | [`?CardPaymentDetails`](../../doc/models/card-payment-details.md) | Optional | Reflects the current status of a card payment. Contains only non-confidential information. | getCardDetails(): ?CardPaymentDetails | setCardDetails(?CardPaymentDetails cardDetails): void | @@ -45,7 +45,7 @@ Represents a payment processed by the Square API. | `shippingAddress` | [`?Address`](../../doc/models/address.md) | Optional | Represents a postal address in a country.
For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | getShippingAddress(): ?Address | setShippingAddress(?Address shippingAddress): void | | `note` | `?string` | Optional | An optional note to include when creating a payment.
**Constraints**: *Maximum Length*: `500` | getNote(): ?string | setNote(?string note): void | | `statementDescriptionIdentifier` | `?string` | Optional | Additional payment information that gets added to the customer's card statement
as part of the statement description.

Note that the `statement_description_identifier` might get truncated on the statement description
to fit the required information including the Square identifier (SQ *) and the name of the
seller taking the payment. | getStatementDescriptionIdentifier(): ?string | setStatementDescriptionIdentifier(?string statementDescriptionIdentifier): void | -| `capabilities` | `?(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. | getCapabilities(): ?array | setCapabilities(?array capabilities): void | +| `capabilities` | `?(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.
- `EDIT_DELAY_ACTION` - The delay_action can be edited. | getCapabilities(): ?array | setCapabilities(?array capabilities): void | | `receiptNumber` | `?string` | Optional | The payment's receipt number.
The field is missing if a payment is canceled.
**Constraints**: *Maximum Length*: `4` | getReceiptNumber(): ?string | setReceiptNumber(?string receiptNumber): void | | `receiptUrl` | `?string` | Optional | The URL for the payment's receipt.
The field is only populated for COMPLETED payments.
**Constraints**: *Maximum Length*: `255` | getReceiptUrl(): ?string | setReceiptUrl(?string receiptUrl): void | | `deviceDetails` | [`?DeviceDetails`](../../doc/models/device-details.md) | Optional | Details about the device that took the payment. | getDeviceDetails(): ?DeviceDetails | setDeviceDetails(?DeviceDetails deviceDetails): void | diff --git a/doc/models/payout.md b/doc/models/payout.md index 1725939c..293d0be1 100644 --- a/doc/models/payout.md +++ b/doc/models/payout.md @@ -21,7 +21,7 @@ external bank account or to the Square balance. | `destination` | [`?Destination`](../../doc/models/destination.md) | Optional | Information about the destination against which the payout was made. | getDestination(): ?Destination | setDestination(?Destination destination): void | | `version` | `?int` | Optional | The version number, which is incremented each time an update is made to this payout record.
The version number helps developers receive event notifications or feeds out of order. | getVersion(): ?int | setVersion(?int version): void | | `type` | [`?string (PayoutType)`](../../doc/models/payout-type.md) | Optional | The type of payout: “BATCH” or “SIMPLE”.
BATCH payouts include a list of payout entries that can be considered settled.
SIMPLE payouts do not have any payout entries associated with them
and will show up as one of the payout entries in a future BATCH payout. | getType(): ?string | setType(?string type): void | -| `payoutFee` | [`?(PayoutFee[])`](../../doc/models/payout-fee.md) | Optional | A list of processing fees and any taxes on the fees assessed by Square for this payout. | getPayoutFee(): ?array | setPayoutFee(?array payoutFee): void | +| `payoutFee` | [`?(PayoutFee[])`](../../doc/models/payout-fee.md) | Optional | A list of transfer fees and any taxes on the fees assessed by Square for this payout. | getPayoutFee(): ?array | setPayoutFee(?array payoutFee): void | | `arrivalDate` | `?string` | Optional | The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination. | getArrivalDate(): ?string | setArrivalDate(?string arrivalDate): void | ## Example (as JSON) diff --git a/doc/models/search-catalog-objects-request.md b/doc/models/search-catalog-objects-request.md index 977434bf..8479255b 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 | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `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. | getCursor(): ?string | setCursor(?string cursor): void | -| `objectTypes` | [`?(string[]) (CatalogObjectType)`](../../doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
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. | getObjectTypes(): ?array | setObjectTypes(?array objectTypes): void | +| `objectTypes` | [`?(string[]) (CatalogObjectType)`](../../doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST,
PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | getObjectTypes(): ?array | setObjectTypes(?array objectTypes): void | | `includeDeletedObjects` | `?bool` | Optional | If `true`, deleted objects will be included in the results. Deleted objects will have their
`is_deleted` field set to `true`. | getIncludeDeletedObjects(): ?bool | setIncludeDeletedObjects(?bool includeDeletedObjects): void | | `includeRelatedObjects` | `?bool` | Optional | If `true`, the response will include additional objects that are related to the
requested objects. Related objects are objects that are referenced by object ID by the objects
in the response. This is helpful if the objects are being fetched for immediate display to a user.
This process only goes one level deep. Objects referenced by the related objects will not be included.
For example:

If the `objects` field of the response contains a CatalogItem, its associated
CatalogCategory objects, CatalogTax objects, CatalogImage objects and
CatalogModifierLists will be returned in the `related_objects` field of the
response. If the `objects` field of the response contains a CatalogItemVariation,
its parent CatalogItem will be returned in the `related_objects` field of
the response.

Default value: `false` | getIncludeRelatedObjects(): ?bool | setIncludeRelatedObjects(?bool includeRelatedObjects): void | | `beginTime` | `?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. | getBeginTime(): ?string | setBeginTime(?string beginTime): void | diff --git a/doc/models/subscription-phase.md b/doc/models/subscription-phase.md index 41622338..be29666d 100644 --- a/doc/models/subscription-phase.md +++ b/doc/models/subscription-phase.md @@ -15,7 +15,7 @@ Describes a phase in a subscription plan. For more information, see | `uid` | `?string` | Optional | The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created. | getUid(): ?string | setUid(?string uid): void | | `cadence` | [`string (SubscriptionCadence)`](../../doc/models/subscription-cadence.md) | Required | Determines the billing cadence of a [Subscription](../../doc/models/subscription.md) | getCadence(): string | setCadence(string cadence): void | | `periods` | `?int` | Optional | The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created. | getPeriods(): ?int | setPeriods(?int periods): void | -| `recurringPriceMoney` | [`Money`](../../doc/models/money.md) | Required | 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. | getRecurringPriceMoney(): Money | setRecurringPriceMoney(Money recurringPriceMoney): void | +| `recurringPriceMoney` | [`?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. | getRecurringPriceMoney(): ?Money | setRecurringPriceMoney(?Money recurringPriceMoney): void | | `ordinal` | `?int` | Optional | The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created. | getOrdinal(): ?int | setOrdinal(?int ordinal): void | ## Example (as JSON) @@ -25,10 +25,7 @@ Describes a phase in a subscription plan. For more information, see "uid": null, "cadence": "DAILY", "periods": null, - "recurring_price_money": { - "amount": null, - "currency": null - }, + "recurring_price_money": null, "ordinal": null } ``` diff --git a/doc/models/terminal-action-action-type.md b/doc/models/terminal-action-action-type.md index 61f563bc..96a39d96 100644 --- a/doc/models/terminal-action-action-type.md +++ b/doc/models/terminal-action-action-type.md @@ -11,5 +11,6 @@ Describes the type of this unit and indicates which field contains the unit info | Name | Description | | --- | --- | +| `PING` | The action represents a request to check if the specific device is
online or currently active with the merchant in question. Does not require an action options value. | | `SAVE_CARD` | Represents a request to save a card for future card-on-file use. | diff --git a/doc/models/terminal-action.md b/doc/models/terminal-action.md index 7b066032..a3f54b0a 100644 --- a/doc/models/terminal-action.md +++ b/doc/models/terminal-action.md @@ -1,6 +1,8 @@ # Terminal Action +Represents an action processed by the Square Terminal. + ## Structure `TerminalAction` @@ -19,6 +21,7 @@ | `appId` | `?string` | Optional | The ID of the application that created the action. | getAppId(): ?string | setAppId(?string appId): void | | `type` | [`?string (TerminalActionActionType)`](../../doc/models/terminal-action-action-type.md) | Optional | Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. | getType(): ?string | setType(?string type): void | | `saveCardOptions` | [`?SaveCardOptions`](../../doc/models/save-card-options.md) | Optional | Describes save-card action fields. | getSaveCardOptions(): ?SaveCardOptions | setSaveCardOptions(?SaveCardOptions saveCardOptions): void | +| `deviceMetadata` | [`?DeviceMetadata`](../../doc/models/device-metadata.md) | Optional | - | getDeviceMetadata(): ?DeviceMetadata | setDeviceMetadata(?DeviceMetadata deviceMetadata): void | ## Example (as JSON) @@ -33,7 +36,8 @@ "updated_at": null, "app_id": null, "type": null, - "save_card_options": null + "save_card_options": null, + "device_metadata": null } ``` diff --git a/src/Apis/BaseApi.php b/src/Apis/BaseApi.php index b710f276..dcb64a1e 100644 --- a/src/Apis/BaseApi.php +++ b/src/Apis/BaseApi.php @@ -43,7 +43,7 @@ class BaseApi */ protected $internalUserAgent; - private static $userAgent = 'Square-PHP-SDK/19.0.1.20220512 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'; + private static $userAgent = 'Square-PHP-SDK/19.1.0.20220616 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'; /** * Constructor that sets the timeout of requests diff --git a/src/Apis/CatalogApi.php b/src/Apis/CatalogApi.php index 11d7e75b..4325ae75 100644 --- a/src/Apis/CatalogApi.php +++ b/src/Apis/CatalogApi.php @@ -511,8 +511,8 @@ public function catalogInfo(): ApiResponse * are not included in the defaults. * * At the current API version the default object types are: - * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, + * PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. * @param int|null $catalogVersion The specific version of the catalog objects to be included in * the response. diff --git a/src/Apis/GiftCardsApi.php b/src/Apis/GiftCardsApi.php index 6c0775d4..e7e76cf6 100644 --- a/src/Apis/GiftCardsApi.php +++ b/src/Apis/GiftCardsApi.php @@ -25,7 +25,7 @@ public function __construct(ConfigurationInterface $config, array $authManagers, /** * Lists all gift cards. You can specify optional filters to retrieve - * a subset of the gift cards. + * a subset of the gift cards. Results are sorted by `created_at` in ascending order. * * @param string|null $type If a [type]($m/GiftCardType) is provided, the endpoint returns gift * cards of the specified type. diff --git a/src/Apis/LoyaltyApi.php b/src/Apis/LoyaltyApi.php index aeee6315..2a09cf23 100644 --- a/src/Apis/LoyaltyApi.php +++ b/src/Apis/LoyaltyApi.php @@ -232,7 +232,7 @@ public function retrieveLoyaltyAccount(string $accountId): ApiResponse } /** - * Adds points to a loyalty account. + * Adds points earned from the base loyalty program to a loyalty account. * * - If you are using the Orders API to manage orders, you only provide the `order_id`. * The endpoint reads the order to compute points to add to the buyer's account. @@ -242,6 +242,8 @@ public function retrieveLoyaltyAccount(string $accountId): ApiResponse * [CalculateLoyaltyPoints]($e/Loyalty/CalculateLoyaltyPoints) to compute the points * that you provide to this endpoint. * + * This endpoint excludes additional points earned from loyalty promotions. + * * @param string $accountId The [loyalty account]($m/LoyaltyAccount) ID to which to add the * points. * @param Models\AccumulateLoyaltyPointsRequest $body An object containing the fields to POST @@ -614,7 +616,7 @@ public function retrieveLoyaltyProgram(string $programId): ApiResponse } /** - * Calculates the points a purchase earns. + * Calculates the points a purchase earns from the base loyalty program. * * - If you are using the Orders API to manage orders, you provide the `order_id` in the request. The * endpoint calculates the points by reading the order. diff --git a/src/Apis/TerminalApi.php b/src/Apis/TerminalApi.php index d442430b..bbe2bcf8 100644 --- a/src/Apis/TerminalApi.php +++ b/src/Apis/TerminalApi.php @@ -24,8 +24,7 @@ public function __construct(ConfigurationInterface $config, array $authManagers, } /** - * Creates a Terminal action request and sends it to the specified device to take a payment - * for the requested amount. + * Creates a Terminal action request and sends it to the specified device. * * @param Models\CreateTerminalActionRequest $body An object containing the fields to POST for * the request. diff --git a/src/ConfigurationDefaults.php b/src/ConfigurationDefaults.php index 4ea45cd9..97e731a8 100644 --- a/src/ConfigurationDefaults.php +++ b/src/ConfigurationDefaults.php @@ -27,7 +27,7 @@ class ConfigurationDefaults public const HTTP_METHODS_TO_RETRY = ['GET', 'PUT']; - public const SQUARE_VERSION = '2022-05-12'; + public const SQUARE_VERSION = '2022-06-16'; public const ADDITIONAL_HEADERS = []; diff --git a/src/Models/AppointmentSegment.php b/src/Models/AppointmentSegment.php index 2b104a8f..5489c401 100644 --- a/src/Models/AppointmentSegment.php +++ b/src/Models/AppointmentSegment.php @@ -17,7 +17,7 @@ class AppointmentSegment implements \JsonSerializable private $durationMinutes; /** - * @var string + * @var string|null */ private $serviceVariationId; @@ -27,7 +27,7 @@ class AppointmentSegment implements \JsonSerializable private $teamMemberId; /** - * @var int + * @var int|null */ private $serviceVariationVersion; @@ -47,15 +47,11 @@ class AppointmentSegment implements \JsonSerializable private $resourceIds; /** - * @param string $serviceVariationId * @param string $teamMemberId - * @param int $serviceVariationVersion */ - public function __construct(string $serviceVariationId, string $teamMemberId, int $serviceVariationVersion) + public function __construct(string $teamMemberId) { - $this->serviceVariationId = $serviceVariationId; $this->teamMemberId = $teamMemberId; - $this->serviceVariationVersion = $serviceVariationVersion; } /** @@ -83,7 +79,7 @@ public function setDurationMinutes(?int $durationMinutes): void * The ID of the [CatalogItemVariation]($m/CatalogItemVariation) object representing the service booked * in this segment. */ - public function getServiceVariationId(): string + public function getServiceVariationId(): ?string { return $this->serviceVariationId; } @@ -93,10 +89,9 @@ public function getServiceVariationId(): string * The ID of the [CatalogItemVariation]($m/CatalogItemVariation) object representing the service booked * in this segment. * - * @required * @maps service_variation_id */ - public function setServiceVariationId(string $serviceVariationId): void + public function setServiceVariationId(?string $serviceVariationId): void { $this->serviceVariationId = $serviceVariationId; } @@ -126,7 +121,7 @@ public function setTeamMemberId(string $teamMemberId): void * Returns Service Variation Version. * The current version of the item variation representing the service booked in this segment. */ - public function getServiceVariationVersion(): int + public function getServiceVariationVersion(): ?int { return $this->serviceVariationVersion; } @@ -135,10 +130,9 @@ public function getServiceVariationVersion(): int * Sets Service Variation Version. * The current version of the item variation representing the service booked in this segment. * - * @required * @maps service_variation_version */ - public function setServiceVariationVersion(int $serviceVariationVersion): void + public function setServiceVariationVersion(?int $serviceVariationVersion): void { $this->serviceVariationVersion = $serviceVariationVersion; } @@ -220,19 +214,23 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) { $json = []; if (isset($this->durationMinutes)) { - $json['duration_minutes'] = $this->durationMinutes; + $json['duration_minutes'] = $this->durationMinutes; + } + if (isset($this->serviceVariationId)) { + $json['service_variation_id'] = $this->serviceVariationId; + } + $json['team_member_id'] = $this->teamMemberId; + if (isset($this->serviceVariationVersion)) { + $json['service_variation_version'] = $this->serviceVariationVersion; } - $json['service_variation_id'] = $this->serviceVariationId; - $json['team_member_id'] = $this->teamMemberId; - $json['service_variation_version'] = $this->serviceVariationVersion; if (isset($this->intermissionMinutes)) { - $json['intermission_minutes'] = $this->intermissionMinutes; + $json['intermission_minutes'] = $this->intermissionMinutes; } if (isset($this->anyTeamMember)) { - $json['any_team_member'] = $this->anyTeamMember; + $json['any_team_member'] = $this->anyTeamMember; } if (isset($this->resourceIds)) { - $json['resource_ids'] = $this->resourceIds; + $json['resource_ids'] = $this->resourceIds; } $json = array_filter($json, function ($val) { return $val !== null; diff --git a/src/Models/BatchRetrieveInventoryChangesRequest.php b/src/Models/BatchRetrieveInventoryChangesRequest.php index 0848ae9a..16a27002 100644 --- a/src/Models/BatchRetrieveInventoryChangesRequest.php +++ b/src/Models/BatchRetrieveInventoryChangesRequest.php @@ -43,6 +43,11 @@ class BatchRetrieveInventoryChangesRequest implements \JsonSerializable */ private $cursor; + /** + * @var int|null + */ + private $limit; + /** * Returns Catalog Object Ids. * The filter to return results by `CatalogObject` ID. @@ -227,6 +232,24 @@ public function setCursor(?string $cursor): void $this->cursor = $cursor; } + /** + * Returns Limit. + */ + public function getLimit(): ?int + { + return $this->limit; + } + + /** + * Sets Limit. + * + * @maps limit + */ + public function setLimit(?int $limit): void + { + $this->limit = $limit; + } + /** * Encode this object to JSON * @@ -260,6 +283,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->cursor)) { $json['cursor'] = $this->cursor; } + if (isset($this->limit)) { + $json['limit'] = $this->limit; + } $json = array_filter($json, function ($val) { return $val !== null; }); diff --git a/src/Models/BatchRetrieveInventoryCountsRequest.php b/src/Models/BatchRetrieveInventoryCountsRequest.php index b08605f6..dbe9c337 100644 --- a/src/Models/BatchRetrieveInventoryCountsRequest.php +++ b/src/Models/BatchRetrieveInventoryCountsRequest.php @@ -33,6 +33,11 @@ class BatchRetrieveInventoryCountsRequest implements \JsonSerializable */ private $states; + /** + * @var int|null + */ + private $limit; + /** * Returns Catalog Object Ids. * The filter to return results by `CatalogObject` ID. @@ -166,6 +171,24 @@ public function setStates(?array $states): void $this->states = $states; } + /** + * Returns Limit. + */ + public function getLimit(): ?int + { + return $this->limit; + } + + /** + * Sets Limit. + * + * @maps limit + */ + public function setLimit(?int $limit): void + { + $this->limit = $limit; + } + /** * Encode this object to JSON * @@ -193,6 +216,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->states)) { $json['states'] = InventoryState::checkValue($this->states); } + if (isset($this->limit)) { + $json['limit'] = $this->limit; + } $json = array_filter($json, function ($val) { return $val !== null; }); diff --git a/src/Models/CalculateLoyaltyPointsResponse.php b/src/Models/CalculateLoyaltyPointsResponse.php index f3e2a915..67bb9d3f 100644 --- a/src/Models/CalculateLoyaltyPointsResponse.php +++ b/src/Models/CalculateLoyaltyPointsResponse.php @@ -49,6 +49,7 @@ public function setErrors(?array $errors): void /** * Returns Points. * The points that the buyer can earn from a specified purchase. + * This value does not include additional points earned from a loyalty promotion. */ public function getPoints(): ?int { @@ -58,6 +59,7 @@ public function getPoints(): ?int /** * Sets Points. * The points that the buyer can earn from a specified purchase. + * This value does not include additional points earned from a loyalty promotion. * * @maps points */ diff --git a/src/Models/CancelTerminalActionResponse.php b/src/Models/CancelTerminalActionResponse.php index 6707a62b..08ccf3c4 100644 --- a/src/Models/CancelTerminalActionResponse.php +++ b/src/Models/CancelTerminalActionResponse.php @@ -44,6 +44,7 @@ public function setErrors(?array $errors): void /** * Returns Action. + * Represents an action processed by the Square Terminal. */ public function getAction(): ?TerminalAction { @@ -52,6 +53,7 @@ public function getAction(): ?TerminalAction /** * Sets Action. + * Represents an action processed by the Square Terminal. * * @maps action */ diff --git a/src/Models/Card.php b/src/Models/Card.php index d00ff2fc..edd5c039 100644 --- a/src/Models/Card.php +++ b/src/Models/Card.php @@ -92,6 +92,11 @@ class Card implements \JsonSerializable */ private $version; + /** + * @var string|null + */ + private $cardCoBrand; + /** * Returns Id. * Unique ID for this card. Generated by Square. @@ -435,6 +440,27 @@ public function setVersion(?int $version): void $this->version = $version; } + /** + * Returns Card Co Brand. + * Indicates the brand for a co-branded card. + */ + public function getCardCoBrand(): ?string + { + return $this->cardCoBrand; + } + + /** + * Sets Card Co Brand. + * Indicates the brand for a co-branded card. + * + * @maps card_co_brand + * @factory \Square\Models\CardCoBrand::checkValue + */ + public function setCardCoBrand(?string $cardCoBrand): void + { + $this->cardCoBrand = $cardCoBrand; + } + /** * Encode this object to JSON * @@ -495,6 +521,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->version)) { $json['version'] = $this->version; } + if (isset($this->cardCoBrand)) { + $json['card_co_brand'] = CardCoBrand::checkValue($this->cardCoBrand); + } $json = array_filter($json, function ($val) { return $val !== null; }); diff --git a/src/Models/CardCoBrand.php b/src/Models/CardCoBrand.php new file mode 100644 index 00000000..e334e893 --- /dev/null +++ b/src/Models/CardCoBrand.php @@ -0,0 +1,39 @@ +delayDuration = $delayDuration; } + /** + * Returns Delay Action. + * The action to be applied to the payment when the `delay_duration` has elapsed. The action must be + * CANCEL or COMPLETE. For more information, see + * [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card- + * payments/delayed-capture#time-threshold). + * + * Default: CANCEL + */ + public function getDelayAction(): ?string + { + return $this->delayAction; + } + + /** + * Sets Delay Action. + * The action to be applied to the payment when the `delay_duration` has elapsed. The action must be + * CANCEL or COMPLETE. For more information, see + * [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card- + * payments/delayed-capture#time-threshold). + * + * Default: CANCEL + * + * @maps delay_action + */ + public function setDelayAction(?string $delayAction): void + { + $this->delayAction = $delayAction; + } + /** * Returns Autocomplete. * If set to `true`, this payment will be completed when possible. If @@ -750,6 +787,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->delayDuration)) { $json['delay_duration'] = $this->delayDuration; } + if (isset($this->delayAction)) { + $json['delay_action'] = $this->delayAction; + } if (isset($this->autocomplete)) { $json['autocomplete'] = $this->autocomplete; } diff --git a/src/Models/CreateTerminalActionRequest.php b/src/Models/CreateTerminalActionRequest.php index c54d006d..45db7b01 100644 --- a/src/Models/CreateTerminalActionRequest.php +++ b/src/Models/CreateTerminalActionRequest.php @@ -59,6 +59,7 @@ public function setIdempotencyKey(string $idempotencyKey): void /** * Returns Action. + * Represents an action processed by the Square Terminal. */ public function getAction(): TerminalAction { @@ -67,6 +68,7 @@ public function getAction(): TerminalAction /** * Sets Action. + * Represents an action processed by the Square Terminal. * * @required * @maps action diff --git a/src/Models/CreateTerminalActionResponse.php b/src/Models/CreateTerminalActionResponse.php index d950886e..4da9094a 100644 --- a/src/Models/CreateTerminalActionResponse.php +++ b/src/Models/CreateTerminalActionResponse.php @@ -44,6 +44,7 @@ public function setErrors(?array $errors): void /** * Returns Action. + * Represents an action processed by the Square Terminal. */ public function getAction(): ?TerminalAction { @@ -52,6 +53,7 @@ public function getAction(): ?TerminalAction /** * Sets Action. + * Represents an action processed by the Square Terminal. * * @maps action */ diff --git a/src/Models/DeviceMetadata.php b/src/Models/DeviceMetadata.php new file mode 100644 index 00000000..e170cbb8 --- /dev/null +++ b/src/Models/DeviceMetadata.php @@ -0,0 +1,373 @@ +batteryPercentage; + } + + /** + * Sets Battery Percentage. + * The Terminal’s remaining battery percentage, between 1-100. + * + * @maps battery_percentage + */ + public function setBatteryPercentage(?string $batteryPercentage): void + { + $this->batteryPercentage = $batteryPercentage; + } + + /** + * Returns Charging State. + * The current charging state of the Terminal. + * Options: `CHARGING`, `NOT_CHARGING` + */ + public function getChargingState(): ?string + { + return $this->chargingState; + } + + /** + * Sets Charging State. + * The current charging state of the Terminal. + * Options: `CHARGING`, `NOT_CHARGING` + * + * @maps charging_state + */ + public function setChargingState(?string $chargingState): void + { + $this->chargingState = $chargingState; + } + + /** + * Returns Location Id. + * The ID of the Square seller business location associated with the Terminal. + */ + public function getLocationId(): ?string + { + return $this->locationId; + } + + /** + * Sets Location Id. + * The ID of the Square seller business location associated with the Terminal. + * + * @maps location_id + */ + public function setLocationId(?string $locationId): void + { + $this->locationId = $locationId; + } + + /** + * Returns Merchant Id. + * The ID of the Square merchant account that is currently signed-in to the Terminal. + */ + public function getMerchantId(): ?string + { + return $this->merchantId; + } + + /** + * Sets Merchant Id. + * The ID of the Square merchant account that is currently signed-in to the Terminal. + * + * @maps merchant_id + */ + public function setMerchantId(?string $merchantId): void + { + $this->merchantId = $merchantId; + } + + /** + * Returns Network Connection Type. + * The Terminal’s current network connection type. + * Options: `WIFI`, `ETHERNET` + */ + public function getNetworkConnectionType(): ?string + { + return $this->networkConnectionType; + } + + /** + * Sets Network Connection Type. + * The Terminal’s current network connection type. + * Options: `WIFI`, `ETHERNET` + * + * @maps network_connection_type + */ + public function setNetworkConnectionType(?string $networkConnectionType): void + { + $this->networkConnectionType = $networkConnectionType; + } + + /** + * Returns Payment Region. + * The country in which the Terminal is authorized to take payments. + */ + public function getPaymentRegion(): ?string + { + return $this->paymentRegion; + } + + /** + * Sets Payment Region. + * The country in which the Terminal is authorized to take payments. + * + * @maps payment_region + */ + public function setPaymentRegion(?string $paymentRegion): void + { + $this->paymentRegion = $paymentRegion; + } + + /** + * Returns Serial Number. + * The unique identifier assigned to the Terminal, which can be found on the lower back + * of the device. + */ + public function getSerialNumber(): ?string + { + return $this->serialNumber; + } + + /** + * Sets Serial Number. + * The unique identifier assigned to the Terminal, which can be found on the lower back + * of the device. + * + * @maps serial_number + */ + public function setSerialNumber(?string $serialNumber): void + { + $this->serialNumber = $serialNumber; + } + + /** + * Returns Os Version. + * The current version of the Terminal’s operating system. + */ + public function getOsVersion(): ?string + { + return $this->osVersion; + } + + /** + * Sets Os Version. + * The current version of the Terminal’s operating system. + * + * @maps os_version + */ + public function setOsVersion(?string $osVersion): void + { + $this->osVersion = $osVersion; + } + + /** + * Returns App Version. + * The current version of the application running on the Terminal. + */ + public function getAppVersion(): ?string + { + return $this->appVersion; + } + + /** + * Sets App Version. + * The current version of the application running on the Terminal. + * + * @maps app_version + */ + public function setAppVersion(?string $appVersion): void + { + $this->appVersion = $appVersion; + } + + /** + * Returns Wifi Network Name. + * The name of the Wi-Fi network to which the Terminal is connected. + */ + public function getWifiNetworkName(): ?string + { + return $this->wifiNetworkName; + } + + /** + * Sets Wifi Network Name. + * The name of the Wi-Fi network to which the Terminal is connected. + * + * @maps wifi_network_name + */ + public function setWifiNetworkName(?string $wifiNetworkName): void + { + $this->wifiNetworkName = $wifiNetworkName; + } + + /** + * Returns Wifi Network Strength. + * The signal strength of the Wi-FI network connection. + * Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT` + */ + public function getWifiNetworkStrength(): ?string + { + return $this->wifiNetworkStrength; + } + + /** + * Sets Wifi Network Strength. + * The signal strength of the Wi-FI network connection. + * Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT` + * + * @maps wifi_network_strength + */ + public function setWifiNetworkStrength(?string $wifiNetworkStrength): void + { + $this->wifiNetworkStrength = $wifiNetworkStrength; + } + + /** + * Returns Ip Address. + * The IP address of the Terminal. + */ + public function getIpAddress(): ?string + { + return $this->ipAddress; + } + + /** + * Sets Ip Address. + * The IP address of the Terminal. + * + * @maps ip_address + */ + public function setIpAddress(?string $ipAddress): void + { + $this->ipAddress = $ipAddress; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->batteryPercentage)) { + $json['battery_percentage'] = $this->batteryPercentage; + } + if (isset($this->chargingState)) { + $json['charging_state'] = $this->chargingState; + } + if (isset($this->locationId)) { + $json['location_id'] = $this->locationId; + } + if (isset($this->merchantId)) { + $json['merchant_id'] = $this->merchantId; + } + if (isset($this->networkConnectionType)) { + $json['network_connection_type'] = $this->networkConnectionType; + } + if (isset($this->paymentRegion)) { + $json['payment_region'] = $this->paymentRegion; + } + if (isset($this->serialNumber)) { + $json['serial_number'] = $this->serialNumber; + } + if (isset($this->osVersion)) { + $json['os_version'] = $this->osVersion; + } + if (isset($this->appVersion)) { + $json['app_version'] = $this->appVersion; + } + if (isset($this->wifiNetworkName)) { + $json['wifi_network_name'] = $this->wifiNetworkName; + } + if (isset($this->wifiNetworkStrength)) { + $json['wifi_network_strength'] = $this->wifiNetworkStrength; + } + if (isset($this->ipAddress)) { + $json['ip_address'] = $this->ipAddress; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/GetTerminalActionResponse.php b/src/Models/GetTerminalActionResponse.php index 741fb241..dd2cab4d 100644 --- a/src/Models/GetTerminalActionResponse.php +++ b/src/Models/GetTerminalActionResponse.php @@ -44,6 +44,7 @@ public function setErrors(?array $errors): void /** * Returns Action. + * Represents an action processed by the Square Terminal. */ public function getAction(): ?TerminalAction { @@ -52,6 +53,7 @@ public function getAction(): ?TerminalAction /** * Sets Action. + * Represents an action processed by the Square Terminal. * * @maps action */ diff --git a/src/Models/GiftCardActivity.php b/src/Models/GiftCardActivity.php index e5430a5c..b504717d 100644 --- a/src/Models/GiftCardActivity.php +++ b/src/Models/GiftCardActivity.php @@ -7,7 +7,10 @@ use stdClass; /** - * Represents an action performed on a gift card that affects its state or balance. + * Represents an action performed on a [gift card]($m/GiftCard) that affects its state or balance. + * A gift card activity contains information about a specific activity type. For example, a `REDEEM` + * activity + * includes a `redeem_activity_details` field that contains information about the redemption. */ class GiftCardActivity implements \JsonSerializable { @@ -123,7 +126,7 @@ public function __construct(string $type, string $locationId) /** * Returns Id. - * The unique ID of the gift card activity. + * The Square-assigned ID of the gift card activity. */ public function getId(): ?string { @@ -132,7 +135,7 @@ public function getId(): ?string /** * Sets Id. - * The unique ID of the gift card activity. + * The Square-assigned ID of the gift card activity. * * @maps id */ @@ -143,7 +146,7 @@ public function setId(?string $id): void /** * Returns Type. - * Indicates the gift card activity type. + * Indicates the type of [gift card activity]($m/GiftCardActivity). */ public function getType(): string { @@ -152,7 +155,7 @@ public function getType(): string /** * Sets Type. - * Indicates the gift card activity type. + * Indicates the type of [gift card activity]($m/GiftCardActivity). * * @required * @maps type @@ -165,7 +168,7 @@ public function setType(string $type): void /** * Returns Location Id. - * The ID of the location at which the activity occurred. + * The ID of the [business location]($m/Location) where the activity occurred. */ public function getLocationId(): string { @@ -174,7 +177,7 @@ public function getLocationId(): string /** * Sets Location Id. - * The ID of the location at which the activity occurred. + * The ID of the [business location]($m/Location) where the activity occurred. * * @required * @maps location_id @@ -206,7 +209,8 @@ public function setCreatedAt(?string $createdAt): void /** * Returns Gift Card Id. - * The gift card ID. The ID is not required if a GAN is present. + * The gift card ID. When creating a gift card activity, `gift_card_id` is not required if + * `gift_card_gan` is specified. */ public function getGiftCardId(): ?string { @@ -215,7 +219,8 @@ public function getGiftCardId(): ?string /** * Sets Gift Card Id. - * The gift card ID. The ID is not required if a GAN is present. + * The gift card ID. When creating a gift card activity, `gift_card_id` is not required if + * `gift_card_gan` is specified. * * @maps gift_card_id */ @@ -226,7 +231,8 @@ public function setGiftCardId(?string $giftCardId): void /** * Returns Gift Card Gan. - * The gift card GAN. The GAN is not required if `gift_card_id` is present. + * The gift card account number (GAN). When creating a gift card activity, `gift_card_gan` + * is not required if `gift_card_id` is specified. */ public function getGiftCardGan(): ?string { @@ -235,7 +241,8 @@ public function getGiftCardGan(): ?string /** * Sets Gift Card Gan. - * The gift card GAN. The GAN is not required if `gift_card_id` is present. + * The gift card account number (GAN). When creating a gift card activity, `gift_card_gan` + * is not required if `gift_card_id` is specified. * * @maps gift_card_gan */ @@ -278,7 +285,7 @@ public function setGiftCardBalanceMoney(?Money $giftCardBalanceMoney): void /** * Returns Load Activity Details. - * Present only when `GiftCardActivityType` is LOAD. + * Represents details about a `LOAD` [gift card activity type]($m/GiftCardActivityType). */ public function getLoadActivityDetails(): ?GiftCardActivityLoad { @@ -287,7 +294,7 @@ public function getLoadActivityDetails(): ?GiftCardActivityLoad /** * Sets Load Activity Details. - * Present only when `GiftCardActivityType` is LOAD. + * Represents details about a `LOAD` [gift card activity type]($m/GiftCardActivityType). * * @maps load_activity_details */ @@ -298,7 +305,7 @@ public function setLoadActivityDetails(?GiftCardActivityLoad $loadActivityDetail /** * Returns Activate Activity Details. - * Describes a gift card activity of the ACTIVATE type. + * Represents details about an `ACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ public function getActivateActivityDetails(): ?GiftCardActivityActivate { @@ -307,7 +314,7 @@ public function getActivateActivityDetails(): ?GiftCardActivityActivate /** * Sets Activate Activity Details. - * Describes a gift card activity of the ACTIVATE type. + * Represents details about an `ACTIVATE` [gift card activity type]($m/GiftCardActivityType). * * @maps activate_activity_details */ @@ -318,7 +325,7 @@ public function setActivateActivityDetails(?GiftCardActivityActivate $activateAc /** * Returns Redeem Activity Details. - * Present only when `GiftCardActivityType` is REDEEM. + * Represents details about a `REDEEM` [gift card activity type]($m/GiftCardActivityType). */ public function getRedeemActivityDetails(): ?GiftCardActivityRedeem { @@ -327,7 +334,7 @@ public function getRedeemActivityDetails(): ?GiftCardActivityRedeem /** * Sets Redeem Activity Details. - * Present only when `GiftCardActivityType` is REDEEM. + * Represents details about a `REDEEM` [gift card activity type]($m/GiftCardActivityType). * * @maps redeem_activity_details */ @@ -338,7 +345,7 @@ public function setRedeemActivityDetails(?GiftCardActivityRedeem $redeemActivity /** * Returns Clear Balance Activity Details. - * Describes a gift card activity of the CLEAR_BALANCE type. + * Represents details about a `CLEAR_BALANCE` [gift card activity type]($m/GiftCardActivityType). */ public function getClearBalanceActivityDetails(): ?GiftCardActivityClearBalance { @@ -347,7 +354,7 @@ public function getClearBalanceActivityDetails(): ?GiftCardActivityClearBalance /** * Sets Clear Balance Activity Details. - * Describes a gift card activity of the CLEAR_BALANCE type. + * Represents details about a `CLEAR_BALANCE` [gift card activity type]($m/GiftCardActivityType). * * @maps clear_balance_activity_details */ @@ -358,7 +365,7 @@ public function setClearBalanceActivityDetails(?GiftCardActivityClearBalance $cl /** * Returns Deactivate Activity Details. - * Describes a gift card activity of the DEACTIVATE type. + * Represents details about a `DEACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ public function getDeactivateActivityDetails(): ?GiftCardActivityDeactivate { @@ -367,7 +374,7 @@ public function getDeactivateActivityDetails(): ?GiftCardActivityDeactivate /** * Sets Deactivate Activity Details. - * Describes a gift card activity of the DEACTIVATE type. + * Represents details about a `DEACTIVATE` [gift card activity type]($m/GiftCardActivityType). * * @maps deactivate_activity_details */ @@ -378,7 +385,7 @@ public function setDeactivateActivityDetails(?GiftCardActivityDeactivate $deacti /** * Returns Adjust Increment Activity Details. - * Describes a gift card activity of the ADJUST_INCREMENT type. + * Represents details about an `ADJUST_INCREMENT` [gift card activity type]($m/GiftCardActivityType). */ public function getAdjustIncrementActivityDetails(): ?GiftCardActivityAdjustIncrement { @@ -387,7 +394,7 @@ public function getAdjustIncrementActivityDetails(): ?GiftCardActivityAdjustIncr /** * Sets Adjust Increment Activity Details. - * Describes a gift card activity of the ADJUST_INCREMENT type. + * Represents details about an `ADJUST_INCREMENT` [gift card activity type]($m/GiftCardActivityType). * * @maps adjust_increment_activity_details */ @@ -399,7 +406,7 @@ public function setAdjustIncrementActivityDetails( /** * Returns Adjust Decrement Activity Details. - * Describes a gift card activity of the ADJUST_DECREMENT type. + * Represents details about an `ADJUST_DECREMENT` [gift card activity type]($m/GiftCardActivityType). */ public function getAdjustDecrementActivityDetails(): ?GiftCardActivityAdjustDecrement { @@ -408,7 +415,7 @@ public function getAdjustDecrementActivityDetails(): ?GiftCardActivityAdjustDecr /** * Sets Adjust Decrement Activity Details. - * Describes a gift card activity of the ADJUST_DECREMENT type. + * Represents details about an `ADJUST_DECREMENT` [gift card activity type]($m/GiftCardActivityType). * * @maps adjust_decrement_activity_details */ @@ -420,7 +427,7 @@ public function setAdjustDecrementActivityDetails( /** * Returns Refund Activity Details. - * Present only when `GiftCardActivityType` is REFUND. + * Represents details about a `REFUND` [gift card activity type]($m/GiftCardActivityType). */ public function getRefundActivityDetails(): ?GiftCardActivityRefund { @@ -429,7 +436,7 @@ public function getRefundActivityDetails(): ?GiftCardActivityRefund /** * Sets Refund Activity Details. - * Present only when `GiftCardActivityType` is REFUND. + * Represents details about a `REFUND` [gift card activity type]($m/GiftCardActivityType). * * @maps refund_activity_details */ @@ -440,7 +447,8 @@ public function setRefundActivityDetails(?GiftCardActivityRefund $refundActivity /** * Returns Unlinked Activity Refund Activity Details. - * Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. + * Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity + * type]($m/GiftCardActivityType). */ public function getUnlinkedActivityRefundActivityDetails(): ?GiftCardActivityUnlinkedActivityRefund { @@ -449,7 +457,8 @@ public function getUnlinkedActivityRefundActivityDetails(): ?GiftCardActivityUnl /** * Sets Unlinked Activity Refund Activity Details. - * Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. + * Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity + * type]($m/GiftCardActivityType). * * @maps unlinked_activity_refund_activity_details */ @@ -461,8 +470,9 @@ public function setUnlinkedActivityRefundActivityDetails( /** * Returns Import Activity Details. - * Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER - * (a third-party gift card). + * Represents details about an `IMPORT` [gift card activity type]($m/GiftCardActivityType). + * This activity type is used when Square imports a third-party gift card, in which case the + * `gan_source` of the gift card is set to `OTHER`. */ public function getImportActivityDetails(): ?GiftCardActivityImport { @@ -471,8 +481,9 @@ public function getImportActivityDetails(): ?GiftCardActivityImport /** * Sets Import Activity Details. - * Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER - * (a third-party gift card). + * Represents details about an `IMPORT` [gift card activity type]($m/GiftCardActivityType). + * This activity type is used when Square imports a third-party gift card, in which case the + * `gan_source` of the gift card is set to `OTHER`. * * @maps import_activity_details */ @@ -483,7 +494,7 @@ public function setImportActivityDetails(?GiftCardActivityImport $importActivity /** * Returns Block Activity Details. - * Describes a gift card activity of the BLOCK type. + * Represents details about a `BLOCK` [gift card activity type]($m/GiftCardActivityType). */ public function getBlockActivityDetails(): ?GiftCardActivityBlock { @@ -492,7 +503,7 @@ public function getBlockActivityDetails(): ?GiftCardActivityBlock /** * Sets Block Activity Details. - * Describes a gift card activity of the BLOCK type. + * Represents details about a `BLOCK` [gift card activity type]($m/GiftCardActivityType). * * @maps block_activity_details */ @@ -503,7 +514,7 @@ public function setBlockActivityDetails(?GiftCardActivityBlock $blockActivityDet /** * Returns Unblock Activity Details. - * Present only when `GiftCardActivityType` is UNBLOCK. + * Represents details about an `UNBLOCK` [gift card activity type]($m/GiftCardActivityType). */ public function getUnblockActivityDetails(): ?GiftCardActivityUnblock { @@ -512,7 +523,7 @@ public function getUnblockActivityDetails(): ?GiftCardActivityUnblock /** * Sets Unblock Activity Details. - * Present only when `GiftCardActivityType` is UNBLOCK. + * Represents details about an `UNBLOCK` [gift card activity type]($m/GiftCardActivityType). * * @maps unblock_activity_details */ @@ -523,7 +534,7 @@ public function setUnblockActivityDetails(?GiftCardActivityUnblock $unblockActiv /** * Returns Import Reversal Activity Details. - * Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER + * Represents details about an `IMPORT_REVERSAL` [gift card activity type]($m/GiftCardActivityType). */ public function getImportReversalActivityDetails(): ?GiftCardActivityImportReversal { @@ -532,7 +543,7 @@ public function getImportReversalActivityDetails(): ?GiftCardActivityImportRever /** * Sets Import Reversal Activity Details. - * Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER + * Represents details about an `IMPORT_REVERSAL` [gift card activity type]($m/GiftCardActivityType). * * @maps import_reversal_activity_details */ diff --git a/src/Models/GiftCardActivityActivate.php b/src/Models/GiftCardActivityActivate.php index f3b3175c..c837e89e 100644 --- a/src/Models/GiftCardActivityActivate.php +++ b/src/Models/GiftCardActivityActivate.php @@ -7,7 +7,7 @@ use stdClass; /** - * Describes a gift card activity of the ACTIVATE type. + * Represents details about an `ACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityActivate implements \JsonSerializable { @@ -70,8 +70,10 @@ public function setAmountMoney(?Money $amountMoney): void /** * Returns Order Id. - * The ID of the order associated with the activity. - * This is required if your application uses the Square Orders API. + * The ID of the [order]($m/Order) that contains the `GIFT_CARD` line item. + * + * Applications that use the Square Orders API to process orders must specify the order ID + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ public function getOrderId(): ?string { @@ -80,8 +82,10 @@ public function getOrderId(): ?string /** * Sets Order Id. - * The ID of the order associated with the activity. - * This is required if your application uses the Square Orders API. + * The ID of the [order]($m/Order) that contains the `GIFT_CARD` line item. + * + * Applications that use the Square Orders API to process orders must specify the order ID + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. * * @maps order_id */ @@ -92,8 +96,10 @@ public function setOrderId(?string $orderId): void /** * Returns Line Item Uid. - * The `line_item_uid` of the gift card line item in an order. - * This is required if your application uses the Square Orders API. + * The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase. + * + * Applications that use the Square Orders API to process orders must specify the line item UID + * in the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ public function getLineItemUid(): ?string { @@ -102,8 +108,10 @@ public function getLineItemUid(): ?string /** * Sets Line Item Uid. - * The `line_item_uid` of the gift card line item in an order. - * This is required if your application uses the Square Orders API. + * The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase. + * + * Applications that use the Square Orders API to process orders must specify the line item UID + * in the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. * * @maps line_item_uid */ @@ -114,8 +122,10 @@ public function setLineItemUid(?string $lineItemUid): void /** * Returns Reference Id. - * If your application does not use the Square Orders API, you can optionally use this field - * to associate the gift card activity with a client-side entity. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom order processing system can use this field to track information + * related to an order or payment. */ public function getReferenceId(): ?string { @@ -124,8 +134,10 @@ public function getReferenceId(): ?string /** * Sets Reference Id. - * If your application does not use the Square Orders API, you can optionally use this field - * to associate the gift card activity with a client-side entity. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom order processing system can use this field to track information + * related to an order or payment. * * @maps reference_id */ @@ -136,11 +148,15 @@ public function setReferenceId(?string $referenceId): void /** * Returns Buyer Payment Instrument Ids. - * Required if your application does not use the Square Orders API. - * This is a list of client-provided payment instrument IDs. + * The payment instrument IDs used to process the gift card purchase, such as a credit card ID + * or bank account ID. + * + * Applications that use a custom order processing system must specify payment instrument IDs in + * the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. * Square uses this information to perform compliance checks. - * If you use the Square Orders API, Square has the necessary instrument IDs to perform necessary - * compliance checks. + * + * For applications that use the Square Orders API to process payments, Square has the necessary + * instrument IDs to perform compliance checks. * * @return string[]|null */ @@ -151,11 +167,15 @@ public function getBuyerPaymentInstrumentIds(): ?array /** * Sets Buyer Payment Instrument Ids. - * Required if your application does not use the Square Orders API. - * This is a list of client-provided payment instrument IDs. + * The payment instrument IDs used to process the gift card purchase, such as a credit card ID + * or bank account ID. + * + * Applications that use a custom order processing system must specify payment instrument IDs in + * the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. * Square uses this information to perform compliance checks. - * If you use the Square Orders API, Square has the necessary instrument IDs to perform necessary - * compliance checks. + * + * For applications that use the Square Orders API to process payments, Square has the necessary + * instrument IDs to perform compliance checks. * * @maps buyer_payment_instrument_ids * diff --git a/src/Models/GiftCardActivityAdjustDecrement.php b/src/Models/GiftCardActivityAdjustDecrement.php index fa5765a5..34e0cbe8 100644 --- a/src/Models/GiftCardActivityAdjustDecrement.php +++ b/src/Models/GiftCardActivityAdjustDecrement.php @@ -7,7 +7,7 @@ use stdClass; /** - * Describes a gift card activity of the ADJUST_DECREMENT type. + * Represents details about an `ADJUST_DECREMENT` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityAdjustDecrement implements \JsonSerializable { @@ -66,6 +66,7 @@ public function setAmountMoney(Money $amountMoney): void /** * Returns Reason. + * Indicates the reason for deducting money from a [gift card]($m/GiftCard). */ public function getReason(): string { @@ -74,6 +75,7 @@ public function getReason(): string /** * Sets Reason. + * Indicates the reason for deducting money from a [gift card]($m/GiftCard). * * @required * @maps reason diff --git a/src/Models/GiftCardActivityAdjustDecrementReason.php b/src/Models/GiftCardActivityAdjustDecrementReason.php index 782081c0..65f3da62 100644 --- a/src/Models/GiftCardActivityAdjustDecrementReason.php +++ b/src/Models/GiftCardActivityAdjustDecrementReason.php @@ -8,6 +8,9 @@ use Square\ApiHelper; use stdClass; +/** + * Indicates the reason for deducting money from a [gift card]($m/GiftCard). + */ class GiftCardActivityAdjustDecrementReason { /** diff --git a/src/Models/GiftCardActivityAdjustIncrement.php b/src/Models/GiftCardActivityAdjustIncrement.php index c2aea6d5..e589bfe0 100644 --- a/src/Models/GiftCardActivityAdjustIncrement.php +++ b/src/Models/GiftCardActivityAdjustIncrement.php @@ -7,7 +7,7 @@ use stdClass; /** - * Describes a gift card activity of the ADJUST_INCREMENT type. + * Represents details about an `ADJUST_INCREMENT` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityAdjustIncrement implements \JsonSerializable { @@ -66,6 +66,7 @@ public function setAmountMoney(Money $amountMoney): void /** * Returns Reason. + * Indicates the reason for adding money to a [gift card]($m/GiftCard). */ public function getReason(): string { @@ -74,6 +75,7 @@ public function getReason(): string /** * Sets Reason. + * Indicates the reason for adding money to a [gift card]($m/GiftCard). * * @required * @maps reason diff --git a/src/Models/GiftCardActivityAdjustIncrementReason.php b/src/Models/GiftCardActivityAdjustIncrementReason.php index 8ec5be58..9836ae94 100644 --- a/src/Models/GiftCardActivityAdjustIncrementReason.php +++ b/src/Models/GiftCardActivityAdjustIncrementReason.php @@ -8,10 +8,13 @@ use Square\ApiHelper; use stdClass; +/** + * Indicates the reason for adding money to a [gift card]($m/GiftCard). + */ class GiftCardActivityAdjustIncrementReason { /** - * Seller gifted a complimentary gift card balance increase. + * The seller gifted a complimentary gift card balance increase. */ public const COMPLIMENTARY = 'COMPLIMENTARY'; diff --git a/src/Models/GiftCardActivityBlock.php b/src/Models/GiftCardActivityBlock.php index 03ba02ff..73349deb 100644 --- a/src/Models/GiftCardActivityBlock.php +++ b/src/Models/GiftCardActivityBlock.php @@ -7,7 +7,7 @@ use stdClass; /** - * Describes a gift card activity of the BLOCK type. + * Represents details about a `BLOCK` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityBlock implements \JsonSerializable { @@ -18,6 +18,7 @@ class GiftCardActivityBlock implements \JsonSerializable /** * Returns Reason. + * Indicates the reason for blocking a [gift card]($m/GiftCard). */ public function getReason(): string { @@ -26,6 +27,7 @@ public function getReason(): string /** * Sets Reason. + * Indicates the reason for blocking a [gift card]($m/GiftCard). * * @maps reason */ diff --git a/src/Models/GiftCardActivityBlockReason.php b/src/Models/GiftCardActivityBlockReason.php index 5e1fe421..a4548c3e 100644 --- a/src/Models/GiftCardActivityBlockReason.php +++ b/src/Models/GiftCardActivityBlockReason.php @@ -8,6 +8,9 @@ use Square\ApiHelper; use stdClass; +/** + * Indicates the reason for blocking a [gift card]($m/GiftCard). + */ class GiftCardActivityBlockReason { /** diff --git a/src/Models/GiftCardActivityClearBalance.php b/src/Models/GiftCardActivityClearBalance.php index 4689d195..3360b953 100644 --- a/src/Models/GiftCardActivityClearBalance.php +++ b/src/Models/GiftCardActivityClearBalance.php @@ -7,7 +7,7 @@ use stdClass; /** - * Describes a gift card activity of the CLEAR_BALANCE type. + * Represents details about a `CLEAR_BALANCE` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityClearBalance implements \JsonSerializable { @@ -26,6 +26,7 @@ public function __construct(string $reason) /** * Returns Reason. + * Indicates the reason for clearing the balance of a [gift card]($m/GiftCard). */ public function getReason(): string { @@ -34,6 +35,7 @@ public function getReason(): string /** * Sets Reason. + * Indicates the reason for clearing the balance of a [gift card]($m/GiftCard). * * @required * @maps reason diff --git a/src/Models/GiftCardActivityClearBalanceReason.php b/src/Models/GiftCardActivityClearBalanceReason.php index 8a262d72..7a3f5168 100644 --- a/src/Models/GiftCardActivityClearBalanceReason.php +++ b/src/Models/GiftCardActivityClearBalanceReason.php @@ -8,6 +8,9 @@ use Square\ApiHelper; use stdClass; +/** + * Indicates the reason for clearing the balance of a [gift card]($m/GiftCard). + */ class GiftCardActivityClearBalanceReason { /** diff --git a/src/Models/GiftCardActivityDeactivate.php b/src/Models/GiftCardActivityDeactivate.php index 47fa48bc..473387eb 100644 --- a/src/Models/GiftCardActivityDeactivate.php +++ b/src/Models/GiftCardActivityDeactivate.php @@ -7,7 +7,7 @@ use stdClass; /** - * Describes a gift card activity of the DEACTIVATE type. + * Represents details about a `DEACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityDeactivate implements \JsonSerializable { @@ -26,6 +26,7 @@ public function __construct(string $reason) /** * Returns Reason. + * Indicates the reason for deactivating a [gift card]($m/GiftCard). */ public function getReason(): string { @@ -34,6 +35,7 @@ public function getReason(): string /** * Sets Reason. + * Indicates the reason for deactivating a [gift card]($m/GiftCard). * * @required * @maps reason diff --git a/src/Models/GiftCardActivityDeactivateReason.php b/src/Models/GiftCardActivityDeactivateReason.php index d6b0f729..02bcd207 100644 --- a/src/Models/GiftCardActivityDeactivateReason.php +++ b/src/Models/GiftCardActivityDeactivateReason.php @@ -8,6 +8,9 @@ use Square\ApiHelper; use stdClass; +/** + * Indicates the reason for deactivating a [gift card]($m/GiftCard). + */ class GiftCardActivityDeactivateReason { /** @@ -16,7 +19,7 @@ class GiftCardActivityDeactivateReason public const SUSPICIOUS_ACTIVITY = 'SUSPICIOUS_ACTIVITY'; /** - * The gift card deactivated for an unknown reason. + * The gift card was deactivated for an unknown reason. */ public const UNKNOWN_REASON = 'UNKNOWN_REASON'; diff --git a/src/Models/GiftCardActivityImport.php b/src/Models/GiftCardActivityImport.php index 6a2870cb..f96bafc7 100644 --- a/src/Models/GiftCardActivityImport.php +++ b/src/Models/GiftCardActivityImport.php @@ -7,8 +7,9 @@ use stdClass; /** - * Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER - * (a third-party gift card). + * Represents details about an `IMPORT` [gift card activity type]($m/GiftCardActivityType). + * This activity type is used when Square imports a third-party gift card, in which case the + * `gan_source` of the gift card is set to `OTHER`. */ class GiftCardActivityImport implements \JsonSerializable { diff --git a/src/Models/GiftCardActivityImportReversal.php b/src/Models/GiftCardActivityImportReversal.php index f9f5ae35..4a5f04c0 100644 --- a/src/Models/GiftCardActivityImportReversal.php +++ b/src/Models/GiftCardActivityImportReversal.php @@ -7,7 +7,7 @@ use stdClass; /** - * Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER + * Represents details about an `IMPORT_REVERSAL` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityImportReversal implements \JsonSerializable { diff --git a/src/Models/GiftCardActivityLoad.php b/src/Models/GiftCardActivityLoad.php index a80c0e48..84630243 100644 --- a/src/Models/GiftCardActivityLoad.php +++ b/src/Models/GiftCardActivityLoad.php @@ -7,7 +7,7 @@ use stdClass; /** - * Present only when `GiftCardActivityType` is LOAD. + * Represents details about a `LOAD` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityLoad implements \JsonSerializable { @@ -70,8 +70,10 @@ public function setAmountMoney(?Money $amountMoney): void /** * Returns Order Id. - * The `order_id` of the order associated with the activity. - * It is populated along with `line_item_uid` and is required if using the Square Orders API. + * The ID of the [order]($m/Order) that contains the `GIFT_CARD` line item. + * + * Applications that use the Square Orders API to process orders must specify the order ID in the + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ public function getOrderId(): ?string { @@ -80,8 +82,10 @@ public function getOrderId(): ?string /** * Sets Order Id. - * The `order_id` of the order associated with the activity. - * It is populated along with `line_item_uid` and is required if using the Square Orders API. + * The ID of the [order]($m/Order) that contains the `GIFT_CARD` line item. + * + * Applications that use the Square Orders API to process orders must specify the order ID in the + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. * * @maps order_id */ @@ -92,8 +96,11 @@ public function setOrderId(?string $orderId): void /** * Returns Line Item Uid. - * The `line_item_uid` of the gift card’s line item in the order associated with the activity. - * It is populated along with `order_id` and is required if using the Square Orders API. + * The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift + * card. + * + * Applications that use the Square Orders API to process orders must specify the line item UID + * in the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ public function getLineItemUid(): ?string { @@ -102,8 +109,11 @@ public function getLineItemUid(): ?string /** * Sets Line Item Uid. - * The `line_item_uid` of the gift card’s line item in the order associated with the activity. - * It is populated along with `order_id` and is required if using the Square Orders API. + * The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift + * card. + * + * Applications that use the Square Orders API to process orders must specify the line item UID + * in the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. * * @maps line_item_uid */ @@ -114,9 +124,11 @@ public function setLineItemUid(?string $lineItemUid): void /** * Returns Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom order processing system can use this field to track information + * related to + * an order or payment. */ public function getReferenceId(): ?string { @@ -125,9 +137,11 @@ public function getReferenceId(): ?string /** * Sets Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom order processing system can use this field to track information + * related to + * an order or payment. * * @maps reference_id */ @@ -138,8 +152,16 @@ public function setReferenceId(?string $referenceId): void /** * Returns Buyer Payment Instrument Ids. - * If you are not using the Orders API, this field is required because it is used to identify a buyer - * to perform compliance checks. + * The payment instrument IDs used to process the order for the additional funds, such as a credit card + * ID + * or bank account ID. + * + * Applications that use a custom order processing system must specify payment instrument IDs in + * the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. + * Square uses this information to perform compliance checks. + * + * For applications that use the Square Orders API to process payments, Square has the necessary + * instrument IDs to perform compliance checks. * * @return string[]|null */ @@ -150,8 +172,16 @@ public function getBuyerPaymentInstrumentIds(): ?array /** * Sets Buyer Payment Instrument Ids. - * If you are not using the Orders API, this field is required because it is used to identify a buyer - * to perform compliance checks. + * The payment instrument IDs used to process the order for the additional funds, such as a credit card + * ID + * or bank account ID. + * + * Applications that use a custom order processing system must specify payment instrument IDs in + * the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. + * Square uses this information to perform compliance checks. + * + * For applications that use the Square Orders API to process payments, Square has the necessary + * instrument IDs to perform compliance checks. * * @maps buyer_payment_instrument_ids * diff --git a/src/Models/GiftCardActivityRedeem.php b/src/Models/GiftCardActivityRedeem.php index c8298c07..423d01c1 100644 --- a/src/Models/GiftCardActivityRedeem.php +++ b/src/Models/GiftCardActivityRedeem.php @@ -7,7 +7,7 @@ use stdClass; /** - * Present only when `GiftCardActivityType` is REDEEM. + * Represents details about a `REDEEM` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityRedeem implements \JsonSerializable { @@ -26,6 +26,11 @@ class GiftCardActivityRedeem implements \JsonSerializable */ private $referenceId; + /** + * @var string|null + */ + private $status; + /** * @param Money $amountMoney */ @@ -69,9 +74,8 @@ public function setAmountMoney(Money $amountMoney): void /** * Returns Payment Id. - * When the Square Payments API is used, Redeem is not called on the Gift Cards API. - * However, when Square reads a Redeem activity from the Gift Cards API, developers need to know the - * associated `payment_id`. + * The ID of the payment that represents the gift card redemption. Square populates this field + * if the payment was processed by Square. */ public function getPaymentId(): ?string { @@ -80,9 +84,8 @@ public function getPaymentId(): ?string /** * Sets Payment Id. - * When the Square Payments API is used, Redeem is not called on the Gift Cards API. - * However, when Square reads a Redeem activity from the Gift Cards API, developers need to know the - * associated `payment_id`. + * The ID of the payment that represents the gift card redemption. Square populates this field + * if the payment was processed by Square. * * @maps payment_id */ @@ -93,9 +96,10 @@ public function setPaymentId(?string $paymentId): void /** * Returns Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom payment processing system can use this field to track information + * related to an order or payment. */ public function getReferenceId(): ?string { @@ -104,9 +108,10 @@ public function getReferenceId(): ?string /** * Sets Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom payment processing system can use this field to track information + * related to an order or payment. * * @maps reference_id */ @@ -115,6 +120,33 @@ public function setReferenceId(?string $referenceId): void $this->referenceId = $referenceId; } + /** + * Returns Status. + * Indicates the status of a [gift card]($m/GiftCard) redemption. This status is relevant only for + * redemptions made from Square products (such as Square Point of Sale) because Square products use a + * two-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` + * status. + */ + public function getStatus(): ?string + { + return $this->status; + } + + /** + * Sets Status. + * Indicates the status of a [gift card]($m/GiftCard) redemption. This status is relevant only for + * redemptions made from Square products (such as Square Point of Sale) because Square products use a + * two-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` + * status. + * + * @maps status + * @factory \Square\Models\GiftCardActivityRedeemStatus::checkValue + */ + public function setStatus(?string $status): void + { + $this->status = $status; + } + /** * Encode this object to JSON * @@ -134,6 +166,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->referenceId)) { $json['reference_id'] = $this->referenceId; } + if (isset($this->status)) { + $json['status'] = GiftCardActivityRedeemStatus::checkValue($this->status); + } $json = array_filter($json, function ($val) { return $val !== null; }); diff --git a/src/Models/GiftCardActivityRedeemStatus.php b/src/Models/GiftCardActivityRedeemStatus.php new file mode 100644 index 00000000..2c7e4cc9 --- /dev/null +++ b/src/Models/GiftCardActivityRedeemStatus.php @@ -0,0 +1,55 @@ +redeemActivityId = $redeemActivityId; - } - /** * Returns Redeem Activity Id. - * The ID for the Redeem activity that needs to be refunded. Hence, the activity it - * refers to has to be of the REDEEM type. + * The ID of the refunded `REDEEM` gift card activity. Square populates this field if the + * `payment_id` in the corresponding [RefundPayment]($e/Refunds/RefundPayment) request + * represents a redemption made by the same gift card. + * + * Applications that use a custom payment processing system can use this field in a + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) + * request to link a refund with a `REDEEM` activity for the same gift card. */ - public function getRedeemActivityId(): string + public function getRedeemActivityId(): ?string { return $this->redeemActivityId; } /** * Sets Redeem Activity Id. - * The ID for the Redeem activity that needs to be refunded. Hence, the activity it - * refers to has to be of the REDEEM type. + * The ID of the refunded `REDEEM` gift card activity. Square populates this field if the + * `payment_id` in the corresponding [RefundPayment]($e/Refunds/RefundPayment) request + * represents a redemption made by the same gift card. + * + * Applications that use a custom payment processing system can use this field in a + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) + * request to link a refund with a `REDEEM` activity for the same gift card. * - * @required * @maps redeem_activity_id */ - public function setRedeemActivityId(string $redeemActivityId): void + public function setRedeemActivityId(?string $redeemActivityId): void { $this->redeemActivityId = $redeemActivityId; } @@ -96,9 +97,10 @@ public function setAmountMoney(?Money $amountMoney): void /** * Returns Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom payment processing system can use this field to track information + * related to an order or payment. */ public function getReferenceId(): ?string { @@ -107,9 +109,10 @@ public function getReferenceId(): ?string /** * Sets Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * + * Applications that use a custom payment processing system can use this field to track information + * related to an order or payment. * * @maps reference_id */ @@ -120,10 +123,12 @@ public function setReferenceId(?string $referenceId): void /** * Returns Payment Id. - * When the Square Payments API is used, Refund is not called on the Gift Cards API. - * However, when Square reads a Refund activity from the Gift Cards API, the developer needs to know - * the - * ID of the payment (made using this gift card) that is being refunded. + * The ID of the refunded payment. Square populates this field if the refund is for a + * payment processed by Square. The payment source can be the same gift card or a cross-tender payment + * from a + * credit card or a different gift card. Cross-tender payments can only be refunded from Square Point + * of Sale + * or other Square products. */ public function getPaymentId(): ?string { @@ -132,10 +137,12 @@ public function getPaymentId(): ?string /** * Sets Payment Id. - * When the Square Payments API is used, Refund is not called on the Gift Cards API. - * However, when Square reads a Refund activity from the Gift Cards API, the developer needs to know - * the - * ID of the payment (made using this gift card) that is being refunded. + * The ID of the refunded payment. Square populates this field if the refund is for a + * payment processed by Square. The payment source can be the same gift card or a cross-tender payment + * from a + * credit card or a different gift card. Cross-tender payments can only be refunded from Square Point + * of Sale + * or other Square products. * * @maps payment_id */ @@ -156,15 +163,17 @@ public function setPaymentId(?string $paymentId): void public function jsonSerialize(bool $asArrayWhenEmpty = false) { $json = []; - $json['redeem_activity_id'] = $this->redeemActivityId; + if (isset($this->redeemActivityId)) { + $json['redeem_activity_id'] = $this->redeemActivityId; + } if (isset($this->amountMoney)) { - $json['amount_money'] = $this->amountMoney; + $json['amount_money'] = $this->amountMoney; } if (isset($this->referenceId)) { - $json['reference_id'] = $this->referenceId; + $json['reference_id'] = $this->referenceId; } if (isset($this->paymentId)) { - $json['payment_id'] = $this->paymentId; + $json['payment_id'] = $this->paymentId; } $json = array_filter($json, function ($val) { return $val !== null; diff --git a/src/Models/GiftCardActivityType.php b/src/Models/GiftCardActivityType.php index f547f434..ed36693e 100644 --- a/src/Models/GiftCardActivityType.php +++ b/src/Models/GiftCardActivityType.php @@ -9,12 +9,14 @@ use stdClass; /** - * Indicates the gift card activity type. + * Indicates the type of [gift card activity]($m/GiftCardActivity). */ class GiftCardActivityType { /** - * Activated a gift card with a balance. + * Activated a gift card with a balance. When a gift card is activated, Square changes + * the gift card state from `PENDING` to `ACTIVE`. A gift card must be in the `ACTIVE` state + * to be used for other balance-changing activities. */ public const ACTIVATE = 'ACTIVATE'; @@ -24,63 +26,71 @@ class GiftCardActivityType public const LOAD = 'LOAD'; /** - * Redeemed a gift card. + * Redeemed a gift card for a purchase. */ public const REDEEM = 'REDEEM'; /** - * Cleared a gift card balance to zero. + * Set the balance of a gift card to zero. */ public const CLEAR_BALANCE = 'CLEAR_BALANCE'; /** - * Permanently blocked a gift card from a balance-changing - * activity. + * Permanently blocked a gift card from balance-changing activities. */ public const DEACTIVATE = 'DEACTIVATE'; /** - * Manually increased a gift card balance. + * Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow. */ public const ADJUST_INCREMENT = 'ADJUST_INCREMENT'; /** - * Manually decreased a gift card balance. + * Deducted money from a gift card outside of a typical `REDEEM` activity flow. */ public const ADJUST_DECREMENT = 'ADJUST_DECREMENT'; /** - * Added money to a gift card because a transaction - * paid with this gift card was refunded. + * Added money to a gift card from a refunded transaction. The refund might be linked to + * a Square payment, depending on how the payment and refund are processed. For example: + * - A gift card payment processed by Square can be refunded to the same gift card. + * - A cross-tender payment processed by Square can be refunded to a gift card. The cross-tender + * payment source can be a credit card or different gift card. + * - A payment processed with a custom processing system (instead of the Square Payments API) can + * be refunded to a gift card. */ public const REFUND = 'REFUND'; /** - * Added money to a gift card because a transaction - * not linked to this gift card was refunded - * to this gift card. + * Added money to a gift card from a refunded transaction that is not linked to the gift card. + * + * This activity type is included for backward compatibility and should not be used to create a refund. + * Instead, use the `REFUND` activity type. */ public const UNLINKED_ACTIVITY_REFUND = 'UNLINKED_ACTIVITY_REFUND'; /** - * Imported a third-party gift card. + * Imported a third-party gift card with a balance. `IMPORT` activities are managed + * by Square and cannot be created using the Gift Card Activities API. */ public const IMPORT = 'IMPORT'; /** - * Temporarily blocked a gift card from balance-changing - * activities. + * Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities + * are managed by Square and cannot be created using the Gift Card Activities API. */ public const BLOCK = 'BLOCK'; /** - * Unblocked a gift card. It can resume balance-changing activities. + * Unblocked a gift card, which enables it to resume balance-changing activities. `UNBLOCK` + * activities are managed by Square and cannot be created using the Gift Card Activities API. */ public const UNBLOCK = 'UNBLOCK'; /** - * A third-party gift card was imported with a balance. - * The import is reversed. + * Reversed the import of a third-party gift card, which sets the gift card state to + * `PENDING` and clears the balance. `IMPORT_REVERSAL` activities are managed by Square and + * cannot be created using the Gift Card Activities API. */ public const IMPORT_REVERSAL = 'IMPORT_REVERSAL'; diff --git a/src/Models/GiftCardActivityUnblock.php b/src/Models/GiftCardActivityUnblock.php index 4647ce0f..e16730d3 100644 --- a/src/Models/GiftCardActivityUnblock.php +++ b/src/Models/GiftCardActivityUnblock.php @@ -7,7 +7,7 @@ use stdClass; /** - * Present only when `GiftCardActivityType` is UNBLOCK. + * Represents details about an `UNBLOCK` [gift card activity type]($m/GiftCardActivityType). */ class GiftCardActivityUnblock implements \JsonSerializable { @@ -18,6 +18,7 @@ class GiftCardActivityUnblock implements \JsonSerializable /** * Returns Reason. + * Indicates the reason for unblocking a [gift card]($m/GiftCard). */ public function getReason(): string { @@ -26,6 +27,7 @@ public function getReason(): string /** * Sets Reason. + * Indicates the reason for unblocking a [gift card]($m/GiftCard). * * @maps reason */ diff --git a/src/Models/GiftCardActivityUnblockReason.php b/src/Models/GiftCardActivityUnblockReason.php index 0a9b3ece..40dacd84 100644 --- a/src/Models/GiftCardActivityUnblockReason.php +++ b/src/Models/GiftCardActivityUnblockReason.php @@ -8,6 +8,9 @@ use Square\ApiHelper; use stdClass; +/** + * Indicates the reason for unblocking a [gift card]($m/GiftCard). + */ class GiftCardActivityUnblockReason { /** diff --git a/src/Models/GiftCardActivityUnlinkedActivityRefund.php b/src/Models/GiftCardActivityUnlinkedActivityRefund.php index 84d88896..2cd93d23 100644 --- a/src/Models/GiftCardActivityUnlinkedActivityRefund.php +++ b/src/Models/GiftCardActivityUnlinkedActivityRefund.php @@ -7,7 +7,8 @@ use stdClass; /** - * Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. + * Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity + * type]($m/GiftCardActivityType). */ class GiftCardActivityUnlinkedActivityRefund implements \JsonSerializable { @@ -69,10 +70,7 @@ public function setAmountMoney(Money $amountMoney): void /** * Returns Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square - * Payments - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. */ public function getReferenceId(): ?string { @@ -81,10 +79,7 @@ public function getReferenceId(): ?string /** * Sets Reference Id. - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square - * Payments - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. * * @maps reference_id */ @@ -95,8 +90,7 @@ public function setReferenceId(?string $referenceId): void /** * Returns Payment Id. - * When using the Square Payments API, the ID of the payment that was refunded to this gift - * card. + * The ID of the refunded payment. This field is not used starting in Square version 2022-06-16. */ public function getPaymentId(): ?string { @@ -105,8 +99,7 @@ public function getPaymentId(): ?string /** * Sets Payment Id. - * When using the Square Payments API, the ID of the payment that was refunded to this gift - * card. + * The ID of the refunded payment. This field is not used starting in Square version 2022-06-16. * * @maps payment_id */ diff --git a/src/Models/ListCatalogRequest.php b/src/Models/ListCatalogRequest.php index ef750249..1b65e205 100644 --- a/src/Models/ListCatalogRequest.php +++ b/src/Models/ListCatalogRequest.php @@ -60,8 +60,8 @@ public function setCursor(?string $cursor): void * are not included in the defaults. * * At the current API version the default object types are: - * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, + * PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. */ public function getTypes(): ?string @@ -82,8 +82,8 @@ public function getTypes(): ?string * are not included in the defaults. * * At the current API version the default object types are: - * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, + * PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. * * @maps types diff --git a/src/Models/Payment.php b/src/Models/Payment.php index 14933251..576c0d93 100644 --- a/src/Models/Payment.php +++ b/src/Models/Payment.php @@ -555,10 +555,9 @@ public function setDelayDuration(?string $delayDuration): void /** * Returns Delay Action. - * The action to be applied to the payment when the `delay_duration` has elapsed. This field - * is read-only. + * The action to be applied to the payment when the `delay_duration` has elapsed. * - * Current values include `CANCEL`. + * Current values include `CANCEL` and `COMPLETE`. */ public function getDelayAction(): ?string { @@ -567,10 +566,9 @@ public function getDelayAction(): ?string /** * Sets Delay Action. - * The action to be applied to the payment when the `delay_duration` has elapsed. This field - * is read-only. + * The action to be applied to the payment when the `delay_duration` has elapsed. * - * Current values include `CANCEL`. + * Current values include `CANCEL` and `COMPLETE`. * * @maps delay_action */ @@ -1072,6 +1070,7 @@ public function setStatementDescriptionIdentifier(?string $statementDescriptionI * - `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. + * - `EDIT_DELAY_ACTION` - The delay_action can be edited. * * @return string[]|null */ @@ -1087,6 +1086,7 @@ public function getCapabilities(): ?array * - `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. + * - `EDIT_DELAY_ACTION` - The delay_action can be edited. * * @maps capabilities * diff --git a/src/Models/PaymentOptions.php b/src/Models/PaymentOptions.php index c082c5eb..eeebfacd 100644 --- a/src/Models/PaymentOptions.php +++ b/src/Models/PaymentOptions.php @@ -95,11 +95,14 @@ public function setDelayDuration(?string $delayDuration): void * `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`. + * payment. + * + * This field cannot be `true` when `autocomplete = true`. + * This field cannot be `true` when an `order_id` isn't specified. * * For more information, see - * [Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take- - * payments#partial-payment-gift-card). + * [Take Partial Payments](https://developer.squareup.com/docs/payments-api/take-payments/card- + * payments/partial-payments-with-gift-cards). * * Default: false */ @@ -114,11 +117,14 @@ public function getAcceptPartialAuthorization(): ?bool * `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`. + * payment. + * + * This field cannot be `true` when `autocomplete = true`. + * This field cannot be `true` when an `order_id` isn't specified. * * For more information, see - * [Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take- - * payments#partial-payment-gift-card). + * [Take Partial Payments](https://developer.squareup.com/docs/payments-api/take-payments/card- + * payments/partial-payments-with-gift-cards). * * Default: false * diff --git a/src/Models/Payout.php b/src/Models/Payout.php index 0e792927..922417a6 100644 --- a/src/Models/Payout.php +++ b/src/Models/Payout.php @@ -285,7 +285,7 @@ public function setType(?string $type): void /** * Returns Payout Fee. - * A list of processing fees and any taxes on the fees assessed by Square for this payout. + * A list of transfer fees and any taxes on the fees assessed by Square for this payout. * * @return PayoutFee[]|null */ @@ -296,7 +296,7 @@ public function getPayoutFee(): ?array /** * Sets Payout Fee. - * A list of processing fees and any taxes on the fees assessed by Square for this payout. + * A list of transfer fees and any taxes on the fees assessed by Square for this payout. * * @maps payout_fee * diff --git a/src/Models/SearchCatalogObjectsRequest.php b/src/Models/SearchCatalogObjectsRequest.php index 8064d7ac..e3f2f7df 100644 --- a/src/Models/SearchCatalogObjectsRequest.php +++ b/src/Models/SearchCatalogObjectsRequest.php @@ -74,8 +74,8 @@ public function setCursor(?string $cursor): void * are not included in the defaults. * * At the current API version the default object types are: - * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, + * PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. * * @return string[]|null @@ -94,8 +94,8 @@ public function getObjectTypes(): ?array * are not included in the defaults. * * At the current API version the default object types are: - * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, + * PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. * * @maps object_types diff --git a/src/Models/SubscriptionPhase.php b/src/Models/SubscriptionPhase.php index efe1dfdc..96d9149e 100644 --- a/src/Models/SubscriptionPhase.php +++ b/src/Models/SubscriptionPhase.php @@ -29,7 +29,7 @@ class SubscriptionPhase implements \JsonSerializable private $periods; /** - * @var Money + * @var Money|null */ private $recurringPriceMoney; @@ -40,12 +40,10 @@ class SubscriptionPhase implements \JsonSerializable /** * @param string $cadence - * @param Money $recurringPriceMoney */ - public function __construct(string $cadence, Money $recurringPriceMoney) + public function __construct(string $cadence) { $this->cadence = $cadence; - $this->recurringPriceMoney = $recurringPriceMoney; } /** @@ -124,7 +122,7 @@ public function setPeriods(?int $periods): void * monetary-amounts) * for more information. */ - public function getRecurringPriceMoney(): Money + public function getRecurringPriceMoney(): ?Money { return $this->recurringPriceMoney; } @@ -139,10 +137,9 @@ public function getRecurringPriceMoney(): Money * monetary-amounts) * for more information. * - * @required * @maps recurring_price_money */ - public function setRecurringPriceMoney(Money $recurringPriceMoney): void + public function setRecurringPriceMoney(?Money $recurringPriceMoney): void { $this->recurringPriceMoney = $recurringPriceMoney; } @@ -182,15 +179,17 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) { $json = []; if (isset($this->uid)) { - $json['uid'] = $this->uid; + $json['uid'] = $this->uid; } - $json['cadence'] = SubscriptionCadence::checkValue($this->cadence); + $json['cadence'] = SubscriptionCadence::checkValue($this->cadence); if (isset($this->periods)) { - $json['periods'] = $this->periods; + $json['periods'] = $this->periods; + } + if (isset($this->recurringPriceMoney)) { + $json['recurring_price_money'] = $this->recurringPriceMoney; } - $json['recurring_price_money'] = $this->recurringPriceMoney; if (isset($this->ordinal)) { - $json['ordinal'] = $this->ordinal; + $json['ordinal'] = $this->ordinal; } $json = array_filter($json, function ($val) { return $val !== null; diff --git a/src/Models/TerminalAction.php b/src/Models/TerminalAction.php index 4b66419b..d52e2efd 100644 --- a/src/Models/TerminalAction.php +++ b/src/Models/TerminalAction.php @@ -6,6 +6,9 @@ use stdClass; +/** + * Represents an action processed by the Square Terminal. + */ class TerminalAction implements \JsonSerializable { /** @@ -58,6 +61,11 @@ class TerminalAction implements \JsonSerializable */ private $saveCardOptions; + /** + * @var DeviceMetadata|null + */ + private $deviceMetadata; + /** * Returns Id. * A unique ID for this `TerminalAction`. @@ -276,6 +284,24 @@ public function setSaveCardOptions(?SaveCardOptions $saveCardOptions): void $this->saveCardOptions = $saveCardOptions; } + /** + * Returns Device Metadata. + */ + public function getDeviceMetadata(): ?DeviceMetadata + { + return $this->deviceMetadata; + } + + /** + * Sets Device Metadata. + * + * @maps device_metadata + */ + public function setDeviceMetadata(?DeviceMetadata $deviceMetadata): void + { + $this->deviceMetadata = $deviceMetadata; + } + /** * Encode this object to JSON * @@ -318,6 +344,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->saveCardOptions)) { $json['save_card_options'] = $this->saveCardOptions; } + if (isset($this->deviceMetadata)) { + $json['device_metadata'] = $this->deviceMetadata; + } $json = array_filter($json, function ($val) { return $val !== null; }); diff --git a/src/Models/TerminalActionActionType.php b/src/Models/TerminalActionActionType.php index 17ccd0e6..987cb230 100644 --- a/src/Models/TerminalActionActionType.php +++ b/src/Models/TerminalActionActionType.php @@ -14,12 +14,18 @@ */ class TerminalActionActionType { + /** + * The action represents a request to check if the specific device is + * online or currently active with the merchant in question. Does not require an action options value. + */ + public const PING = 'PING'; + /** * Represents a request to save a card for future card-on-file use. */ public const SAVE_CARD = 'SAVE_CARD'; - private const _ALL_VALUES = [self::SAVE_CARD]; + private const _ALL_VALUES = [self::PING, self::SAVE_CARD]; /** * Ensures that all the given values are present in this Enum. diff --git a/src/SquareClient.php b/src/SquareClient.php index ed4783de..3df21df2 100644 --- a/src/SquareClient.php +++ b/src/SquareClient.php @@ -271,7 +271,7 @@ public function getBearerAuthCredentials(): ?BearerAuthCredentials */ public function getSdkVersion(): string { - return '19.0.1.20220512'; + return '19.1.0.20220616'; } /**