diff --git a/composer.json b/composer.json index 54bcdf91..6420d889 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": "37.1.1.20240717", + "version": "38.0.0.20240821", "type": "library", "keywords": [ "Square", @@ -48,7 +48,7 @@ "lint-src-fix": "phpcbf --standard=phpcs-ruleset.xml src/", "lint-tests": "phpcs --standard=phpcs-ruleset.xml tests/", "lint-tests-fix": "phpcbf --standard=phpcs-ruleset.xml tests/", - "analyze": "phan --allow-polyfill-parser", + "analyze": "phan --allow-polyfill-parser -p", "lint": [ "@lint-src", "@lint-tests" diff --git a/doc/apis/catalog.md b/doc/apis/catalog.md index b5a2422f..23345192 100644 --- a/doc/apis/catalog.md +++ b/doc/apis/catalog.md @@ -39,7 +39,7 @@ children. IDs can be deleted. The response will only include IDs that were actually deleted. -To ensure consistency, only one delete request is processed at a time per seller account. +To ensure consistency, only one delete request is processed at a time per seller account. While one (batch or non-batch) delete request is being processed, other (batched and non-batched) delete requests are rejected with the `429` error code. @@ -144,7 +144,7 @@ batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000. -To ensure consistency, only one update request is processed at a time per seller account. +To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the `429` error code. @@ -520,7 +520,7 @@ var_dump($apiResponse->getHeaders()); Creates a new or updates the specified [CatalogObject](../../doc/models/catalog-object.md). -To ensure consistency, only one update request is processed at a time per seller account. +To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the `429` error code. @@ -614,7 +614,7 @@ are also deleted. For example, deleting a [CatalogItem](../../doc/models/catalog will also delete all of its [CatalogItemVariation](../../doc/models/catalog-item-variation.md) children. -To ensure consistency, only one delete request is processed at a time per seller account. +To ensure consistency, only one delete request is processed at a time per seller account. While one (batch or non-batch) delete request is being processed, other (batched and non-batched) delete requests are rejected with the `429` error code. diff --git a/doc/apis/gift-card-activities.md b/doc/apis/gift-card-activities.md index 6d14649e..389b35dc 100644 --- a/doc/apis/gift-card-activities.md +++ b/doc/apis/gift-card-activities.md @@ -71,8 +71,7 @@ var_dump($apiResponse->getHeaders()); # Create Gift Card Activity Creates a gift card activity to manage the balance or state of a [gift card](../../doc/models/gift-card.md). -For example, you create an `ACTIVATE` activity to activate a gift card with an initial balance -before the gift card can be used. +For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before first use. ```php function createGiftCardActivity(CreateGiftCardActivityRequest $body): ApiResponse diff --git a/doc/apis/gift-cards.md b/doc/apis/gift-cards.md index f03d9309..3c81676e 100644 --- a/doc/apis/gift-cards.md +++ b/doc/apis/gift-cards.md @@ -67,9 +67,11 @@ var_dump($apiResponse->getHeaders()); # Create Gift Card -Creates a digital gift card or registers a physical (plastic) gift card. After the gift card -is created, you must call [CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) -to activate the card with an initial balance before it can be used for payment. +Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card +has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call +[CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) and create an `ACTIVATE` +activity with the initial balance. Alternatively, you can use [RefundPayment](../../doc/apis/refunds.md#refund-payment) +to refund a payment to the new gift card. ```php function createGiftCard(CreateGiftCardRequest $body): ApiResponse diff --git a/doc/apis/o-auth.md b/doc/apis/o-auth.md index ac52d8ed..84c0f767 100644 --- a/doc/apis/o-auth.md +++ b/doc/apis/o-auth.md @@ -154,18 +154,10 @@ where `ACCESS_TOKEN` is a If the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` error. -:information_source: **Note** This endpoint does not require authentication. - ```php -function retrieveTokenStatus(string $authorization): ApiResponse +function retrieveTokenStatus(): ApiResponse ``` -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `authorization` | `string` | Header, Required | Client APPLICATION_SECRET | - ## Response Type This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` method on this instance returns the response data which is of type [`RetrieveTokenStatusResponse`](../../doc/models/retrieve-token-status-response.md). @@ -173,9 +165,7 @@ This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` met ## Example Usage ```php -$authorization = 'Client CLIENT_SECRET'; - -$apiResponse = $oAuthApi->retrieveTokenStatus($authorization); +$apiResponse = $oAuthApi->retrieveTokenStatus(); if ($apiResponse->isSuccess()) { $retrieveTokenStatusResponse = $apiResponse->getResult(); diff --git a/doc/apis/payments.md b/doc/apis/payments.md index 0e0b78de..a98e5fba 100644 --- a/doc/apis/payments.md +++ b/doc/apis/payments.md @@ -38,7 +38,10 @@ function listPayments( ?int $total = null, ?string $last4 = null, ?string $cardBrand = null, - ?int $limit = null + ?int $limit = null, + ?bool $isOfflinePayment = false, + ?string $offlineBeginTime = null, + ?string $offlineEndTime = null ): ApiResponse ``` @@ -55,6 +58,9 @@ function listPayments( | `last4` | `?string` | Query, Optional | The last four digits of a payment card. | | `cardBrand` | `?string` | Query, Optional | The brand of the payment card (for example, VISA). | | `limit` | `?int` | Query, Optional | The maximum number of results to be returned in a single page.
It is possible to receive fewer results than the specified limit on a given page.

The default value of 100 is also the maximum allowed value. If the provided value is
greater than 100, it is ignored and the default value is used instead.

Default: `100` | +| `isOfflinePayment` | `?bool` | Query, Optional | Whether the payment was taken offline or not. | +| `offlineBeginTime` | `?string` | Query, Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | +| `offlineEndTime` | `?string` | Query, Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | ## Response Type @@ -63,7 +69,20 @@ This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` met ## Example Usage ```php -$apiResponse = $paymentsApi->listPayments(); +$isOfflinePayment = false; + +$apiResponse = $paymentsApi->listPayments( + null, + null, + null, + null, + null, + null, + null, + null, + null, + $isOfflinePayment +); if ($apiResponse->isSuccess()) { $listPaymentsResponse = $apiResponse->getResult(); diff --git a/doc/client.md b/doc/client.md index 37bfe52d..15eb8279 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*: `'2024-07-17'` | +| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2024-08-21'` | | `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` | @@ -30,7 +30,7 @@ $client = SquareClientBuilder::init() 'AccessToken' ) ) - ->squareVersion('2024-07-17') + ->squareVersion('2024-08-21') ->environment('production') ->customUrl('https://connect.squareup.com') ->build(); @@ -60,7 +60,7 @@ $client = SquareClientBuilder::init() 'AccessToken' ) ) - ->squareVersion('2024-07-17') + ->squareVersion('2024-08-21') ->build(); $apiResponse = $client->getLocationsApi()->listLocations(); diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index ae27d89e..cca61ce4 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -35,6 +35,7 @@ Describes a request to create a payment using | `cashDetails` | [`?CashPaymentDetails`](../../doc/models/cash-payment-details.md) | Optional | Stores details about a cash payment. Contains only non-confidential information. For more information, see
[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments). | getCashDetails(): ?CashPaymentDetails | setCashDetails(?CashPaymentDetails cashDetails): void | | `externalDetails` | [`?ExternalPaymentDetails`](../../doc/models/external-payment-details.md) | Optional | Stores details about an external payment. Contains only non-confidential information.
For more information, see
[Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments). | getExternalDetails(): ?ExternalPaymentDetails | setExternalDetails(?ExternalPaymentDetails externalDetails): void | | `customerDetails` | [`?CustomerDetails`](../../doc/models/customer-details.md) | Optional | Details about the customer making the payment. | getCustomerDetails(): ?CustomerDetails | setCustomerDetails(?CustomerDetails customerDetails): void | +| `offlinePaymentDetails` | [`?OfflinePaymentDetails`](../../doc/models/offline-payment-details.md) | Optional | Details specific to offline payments. | getOfflinePaymentDetails(): ?OfflinePaymentDetails | setOfflinePaymentDetails(?OfflinePaymentDetails offlinePaymentDetails): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-activate.md b/doc/models/gift-card-activity-activate.md index 4904c5e5..20c7cf76 100644 --- a/doc/models/gift-card-activity-activate.md +++ b/doc/models/gift-card-activity-activate.md @@ -15,7 +15,7 @@ Represents details about an `ACTIVATE` [gift card activity type](../../doc/model | `orderId` | `?string` | Optional | The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.

Applications that use the Square Orders API to process orders must specify the order ID
[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) 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](api-endpoint:GiftCardActivities-CreateGiftCardActivity) 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](api-endpoint: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. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): 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](api-endpoint: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.

Each buyer payment instrument ID can contain a maximum of 255 characters. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-load.md b/doc/models/gift-card-activity-load.md index 11d288d9..9d47861b 100644 --- a/doc/models/gift-card-activity-load.md +++ b/doc/models/gift-card-activity-load.md @@ -15,7 +15,7 @@ Represents details about a `LOAD` [gift card activity type](../../doc/models/gif | `orderId` | `?string` | Optional | The ID of the [order](entity: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](api-endpoint:GiftCardActivities-CreateGiftCardActivity) 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](api-endpoint:GiftCardActivities-CreateGiftCardActivity) 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](api-endpoint: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. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): 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](api-endpoint: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.

Each buyer payment instrument ID can contain a maximum of 255 characters. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-refund.md b/doc/models/gift-card-activity-refund.md index 2918caff..26d9de5c 100644 --- a/doc/models/gift-card-activity-refund.md +++ b/doc/models/gift-card-activity-refund.md @@ -11,10 +11,10 @@ Represents details about a `REFUND` [gift card activity type](../../doc/models/g | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `redeemActivityId` | `?string` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the
`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request
represents a redemption made by the same gift card. Note that you must use `RefundPayment`
to refund a gift card payment to the same gift card if the payment was processed by Square.

For applications that use a custom payment processing system, this field is required when creating
a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. | 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](api-endpoint:Refunds-RefundPayment) request
represents a gift card redemption.

For applications that use a custom payment processing system, this field is required when creating
a `REFUND` activity. The provided `REDEEM` activity ID must be linked to 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 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. Square populates this field if the refund is for a
payment processed by Square and one of the following conditions is true:

- The Refunds API is used to refund a gift card payment to the same gift card.
- A seller initiated the refund from Square Point of Sale or the Seller Dashboard. The payment source can be the
same gift card or a cross-tender payment from a credit card or a different gift card. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | +| `paymentId` | `?string` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a
payment processed by Square. This field matches the `payment_id` in the corresponding
[RefundPayment](api-endpoint:Refunds-RefundPayment) request. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-type.md b/doc/models/gift-card-activity-type.md index 637f73d2..53df15bc 100644 --- a/doc/models/gift-card-activity-type.md +++ b/doc/models/gift-card-activity-type.md @@ -18,7 +18,7 @@ Indicates the type of [gift card activity](../../doc/models/gift-card-activity.m | `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. A `REFUND` activity 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 using Square Point of Sale,
the Square Seller Dashboard, or the Refunds API.
- A cross-tender payment processed by Square can be refunded to a gift card using Square Point of Sale or the
Square Seller Dashboard. The payment source might be a credit card or different gift card.
- A payment processed using a custom payment processing system can be refunded to the same gift card. | +| `REFUND` | Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to
a Square payment, depending on how the payment and refund are processed. For example:

- A payment processed by Square can be refunded to a `PENDING` or `ACTIVE` gift card using the Square
Seller Dashboard, Square Point of Sale, or Refunds API.
- A payment processed using a custom processing system can be refunded to the same gift card. | | `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card from a refunded transaction that was processed using a custom payment
processing system and not linked to the gift card. | | `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. | diff --git a/doc/models/gift-card-status.md b/doc/models/gift-card-status.md index f66369cc..29540465 100644 --- a/doc/models/gift-card-status.md +++ b/doc/models/gift-card-status.md @@ -14,5 +14,5 @@ Indicates the gift card state. | `ACTIVE` | The gift card is active and can be used as a payment source. | | `DEACTIVATED` | Any activity that changes the gift card balance is permanently forbidden. | | `BLOCKED` | Any activity that changes the gift card balance is temporarily forbidden. | -| `PENDING` | The gift card is pending activation.
This is the initial state when a gift card is created. You must activate the gift card
before it can be used. | +| `PENDING` | The gift card is pending activation.
This is the initial state when a gift card is created. Typically, you'll call
[CreateGiftCardActivity](../../doc/apis/gift-card-activities.md#create-gift-card-activity) to create an
`ACTIVATE` activity that activates the gift card with an initial balance before first use. | diff --git a/doc/models/list-payments-request.md b/doc/models/list-payments-request.md index e41139aa..77d0891a 100644 --- a/doc/models/list-payments-request.md +++ b/doc/models/list-payments-request.md @@ -23,6 +23,9 @@ The maximum results per page is 100. | `last4` | `?string` | Optional | The last four digits of a payment card. | getLast4(): ?string | setLast4(?string last4): void | | `cardBrand` | `?string` | Optional | The brand of the payment card (for example, VISA). | getCardBrand(): ?string | setCardBrand(?string cardBrand): void | | `limit` | `?int` | Optional | The maximum number of results to be returned in a single page.
It is possible to receive fewer results than the specified limit on a given page.

The default value of 100 is also the maximum allowed value. If the provided value is
greater than 100, it is ignored and the default value is used instead.

Default: `100` | getLimit(): ?int | setLimit(?int limit): void | +| `isOfflinePayment` | `?bool` | Optional | Whether the payment was taken offline or not. | getIsOfflinePayment(): ?bool | setIsOfflinePayment(?bool isOfflinePayment): void | +| `offlineBeginTime` | `?string` | Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | getOfflineBeginTime(): ?string | setOfflineBeginTime(?string offlineBeginTime): void | +| `offlineEndTime` | `?string` | Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | getOfflineEndTime(): ?string | setOfflineEndTime(?string offlineEndTime): void | ## Example (as JSON) diff --git a/doc/models/offline-payment-details.md b/doc/models/offline-payment-details.md new file mode 100644 index 00000000..0a43a74c --- /dev/null +++ b/doc/models/offline-payment-details.md @@ -0,0 +1,23 @@ + +# Offline Payment Details + +Details specific to offline payments. + +## Structure + +`OfflinePaymentDetails` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `clientCreatedAt` | `?string` | Optional | The client-side timestamp of when the offline payment was created, in RFC 3339 format.
**Constraints**: *Maximum Length*: `32` | getClientCreatedAt(): ?string | setClientCreatedAt(?string clientCreatedAt): void | + +## Example (as JSON) + +```json +{ + "client_created_at": "client_created_at6" +} +``` + diff --git a/doc/models/payment.md b/doc/models/payment.md index 0c091ae0..f4a5e3e5 100644 --- a/doc/models/payment.md +++ b/doc/models/payment.md @@ -52,6 +52,7 @@ Represents a payment processed by the Square API. | `deviceDetails` | [`?DeviceDetails`](../../doc/models/device-details.md) | Optional | Details about the device that took the payment. | getDeviceDetails(): ?DeviceDetails | setDeviceDetails(?DeviceDetails deviceDetails): void | | `applicationDetails` | [`?ApplicationDetails`](../../doc/models/application-details.md) | Optional | Details about the application that took the payment. | getApplicationDetails(): ?ApplicationDetails | setApplicationDetails(?ApplicationDetails applicationDetails): void | | `isOfflinePayment` | `?bool` | Optional | Whether or not this payment was taken offline. | getIsOfflinePayment(): ?bool | setIsOfflinePayment(?bool isOfflinePayment): void | +| `offlinePaymentDetails` | [`?OfflinePaymentDetails`](../../doc/models/offline-payment-details.md) | Optional | Details specific to offline payments. | getOfflinePaymentDetails(): ?OfflinePaymentDetails | setOfflinePaymentDetails(?OfflinePaymentDetails offlinePaymentDetails): void | | `versionToken` | `?string` | Optional | Used for optimistic concurrency. This opaque token identifies a specific version of the
`Payment` object. | getVersionToken(): ?string | setVersionToken(?string versionToken): void | ## Example (as JSON) diff --git a/src/Apis/GiftCardActivitiesApi.php b/src/Apis/GiftCardActivitiesApi.php index 556c0ef7..718247e4 100644 --- a/src/Apis/GiftCardActivitiesApi.php +++ b/src/Apis/GiftCardActivitiesApi.php @@ -84,8 +84,8 @@ public function listGiftCardActivities( /** * Creates a gift card activity to manage the balance or state of a [gift card]($m/GiftCard). - * For example, you create an `ACTIVATE` activity to activate a gift card with an initial balance - * before the gift card can be used. + * For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before + * first use. * * @param CreateGiftCardActivityRequest $body An object containing the fields to POST for the * request. diff --git a/src/Apis/GiftCardsApi.php b/src/Apis/GiftCardsApi.php index da930d89..c689a91e 100644 --- a/src/Apis/GiftCardsApi.php +++ b/src/Apis/GiftCardsApi.php @@ -73,9 +73,12 @@ public function listGiftCards( } /** - * Creates a digital gift card or registers a physical (plastic) gift card. After the gift card - * is created, you must call [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) - * to activate the card with an initial balance before it can be used for payment. + * Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card + * has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) and create an `ACTIVATE` + * activity with the initial balance. Alternatively, you can use + * [RefundPayment]($e/Refunds/RefundPayment) + * to refund a payment to the new gift card. * * @param CreateGiftCardRequest $body An object containing the fields to POST for the request. * See the corresponding object definition for field details. diff --git a/src/Apis/OAuthApi.php b/src/Apis/OAuthApi.php index b691c6db..d32d3658 100644 --- a/src/Apis/OAuthApi.php +++ b/src/Apis/OAuthApi.php @@ -107,14 +107,11 @@ public function obtainToken(ObtainTokenRequest $body): ApiResponse * If the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` * error. * - * @param string $authorization Client APPLICATION_SECRET - * * @return ApiResponse Response from the API call */ - public function retrieveTokenStatus(string $authorization): ApiResponse + public function retrieveTokenStatus(): ApiResponse { - $_reqBuilder = $this->requestBuilder(RequestMethod::POST, '/oauth2/token/status') - ->parameters(HeaderParam::init('Authorization', $authorization)); + $_reqBuilder = $this->requestBuilder(RequestMethod::POST, '/oauth2/token/status')->auth('global'); $_resHandler = $this->responseHandler()->type(RetrieveTokenStatusResponse::class)->returnApiResponse(); diff --git a/src/Apis/PaymentsApi.php b/src/Apis/PaymentsApi.php index 83a21618..e5f43efa 100644 --- a/src/Apis/PaymentsApi.php +++ b/src/Apis/PaymentsApi.php @@ -62,6 +62,23 @@ class PaymentsApi extends BaseApi * greater than 100, it is ignored and the default value is used instead. * * Default: `100` + * @param bool|null $isOfflinePayment Whether the payment was taken offline or not. + * @param string|null $offlineBeginTime Indicates the start of the time range for which to + * retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments + * without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. + * @param string|null $offlineEndTime Indicates the end of the time range for which to retrieve + * offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments + * without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. * * @return ApiResponse Response from the API call */ @@ -74,7 +91,10 @@ public function listPayments( ?int $total = null, ?string $last4 = null, ?string $cardBrand = null, - ?int $limit = null + ?int $limit = null, + ?bool $isOfflinePayment = false, + ?string $offlineBeginTime = null, + ?string $offlineEndTime = null ): ApiResponse { $_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/payments') ->auth('global') @@ -87,7 +107,10 @@ public function listPayments( QueryParam::init('total', $total), QueryParam::init('last_4', $last4), QueryParam::init('card_brand', $cardBrand), - QueryParam::init('limit', $limit) + QueryParam::init('limit', $limit), + QueryParam::init('is_offline_payment', $isOfflinePayment), + QueryParam::init('offline_begin_time', $offlineBeginTime), + QueryParam::init('offline_end_time', $offlineEndTime) ); $_resHandler = $this->responseHandler()->type(ListPaymentsResponse::class)->returnApiResponse(); diff --git a/src/ConfigurationDefaults.php b/src/ConfigurationDefaults.php index 53f66261..a515d474 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 = '2024-07-17'; + public const SQUARE_VERSION = '2024-08-21'; public const ADDITIONAL_HEADERS = []; diff --git a/src/Models/Builders/CreatePaymentRequestBuilder.php b/src/Models/Builders/CreatePaymentRequestBuilder.php index e700cc33..68624221 100644 --- a/src/Models/Builders/CreatePaymentRequestBuilder.php +++ b/src/Models/Builders/CreatePaymentRequestBuilder.php @@ -11,6 +11,7 @@ use Square\Models\CustomerDetails; use Square\Models\ExternalPaymentDetails; use Square\Models\Money; +use Square\Models\OfflinePaymentDetails; /** * Builder for model CreatePaymentRequest @@ -226,6 +227,15 @@ public function customerDetails(?CustomerDetails $value): self return $this; } + /** + * Sets offline payment details field. + */ + public function offlinePaymentDetails(?OfflinePaymentDetails $value): self + { + $this->instance->setOfflinePaymentDetails($value); + return $this; + } + /** * Initializes a new create payment request object. */ diff --git a/src/Models/Builders/ListPaymentsRequestBuilder.php b/src/Models/Builders/ListPaymentsRequestBuilder.php index 4351eaac..f038f314 100644 --- a/src/Models/Builders/ListPaymentsRequestBuilder.php +++ b/src/Models/Builders/ListPaymentsRequestBuilder.php @@ -194,6 +194,60 @@ public function unsetLimit(): self return $this; } + /** + * Sets is offline payment field. + */ + public function isOfflinePayment(?bool $value): self + { + $this->instance->setIsOfflinePayment($value); + return $this; + } + + /** + * Unsets is offline payment field. + */ + public function unsetIsOfflinePayment(): self + { + $this->instance->unsetIsOfflinePayment(); + return $this; + } + + /** + * Sets offline begin time field. + */ + public function offlineBeginTime(?string $value): self + { + $this->instance->setOfflineBeginTime($value); + return $this; + } + + /** + * Unsets offline begin time field. + */ + public function unsetOfflineBeginTime(): self + { + $this->instance->unsetOfflineBeginTime(); + return $this; + } + + /** + * Sets offline end time field. + */ + public function offlineEndTime(?string $value): self + { + $this->instance->setOfflineEndTime($value); + return $this; + } + + /** + * Unsets offline end time field. + */ + public function unsetOfflineEndTime(): self + { + $this->instance->unsetOfflineEndTime(); + return $this; + } + /** * Initializes a new list payments request object. */ diff --git a/src/Models/Builders/OfflinePaymentDetailsBuilder.php b/src/Models/Builders/OfflinePaymentDetailsBuilder.php new file mode 100644 index 00000000..0d533692 --- /dev/null +++ b/src/Models/Builders/OfflinePaymentDetailsBuilder.php @@ -0,0 +1,51 @@ +instance = $instance; + } + + /** + * Initializes a new offline payment details Builder object. + */ + public static function init(): self + { + return new self(new OfflinePaymentDetails()); + } + + /** + * Sets client created at field. + */ + public function clientCreatedAt(?string $value): self + { + $this->instance->setClientCreatedAt($value); + return $this; + } + + /** + * Initializes a new offline payment details object. + */ + public function build(): OfflinePaymentDetails + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/PaymentBuilder.php b/src/Models/Builders/PaymentBuilder.php index c701bdfd..4ab50cba 100644 --- a/src/Models/Builders/PaymentBuilder.php +++ b/src/Models/Builders/PaymentBuilder.php @@ -15,6 +15,7 @@ use Square\Models\DigitalWalletDetails; use Square\Models\ExternalPaymentDetails; use Square\Models\Money; +use Square\Models\OfflinePaymentDetails; use Square\Models\Payment; use Square\Models\RiskEvaluation; use Square\Models\SquareAccountDetails; @@ -305,6 +306,15 @@ public function teamMemberId(?string $value): self return $this; } + /** + * Unsets team member id field. + */ + public function unsetTeamMemberId(): self + { + $this->instance->unsetTeamMemberId(); + return $this; + } + /** * Sets refund ids field. */ @@ -422,6 +432,15 @@ public function isOfflinePayment(?bool $value): self return $this; } + /** + * Sets offline payment details field. + */ + public function offlinePaymentDetails(?OfflinePaymentDetails $value): self + { + $this->instance->setOfflinePaymentDetails($value); + return $this; + } + /** * Sets version token field. */ diff --git a/src/Models/CreatePaymentRequest.php b/src/Models/CreatePaymentRequest.php index f4d8c2e1..a2434437 100644 --- a/src/Models/CreatePaymentRequest.php +++ b/src/Models/CreatePaymentRequest.php @@ -127,6 +127,11 @@ class CreatePaymentRequest implements \JsonSerializable */ private $customerDetails; + /** + * @var OfflinePaymentDetails|null + */ + private $offlinePaymentDetails; + /** * @param string $sourceId * @param string $idempotencyKey @@ -791,6 +796,26 @@ public function setCustomerDetails(?CustomerDetails $customerDetails): void $this->customerDetails = $customerDetails; } + /** + * Returns Offline Payment Details. + * Details specific to offline payments. + */ + public function getOfflinePaymentDetails(): ?OfflinePaymentDetails + { + return $this->offlinePaymentDetails; + } + + /** + * Sets Offline Payment Details. + * Details specific to offline payments. + * + * @maps offline_payment_details + */ + public function setOfflinePaymentDetails(?OfflinePaymentDetails $offlinePaymentDetails): void + { + $this->offlinePaymentDetails = $offlinePaymentDetails; + } + /** * Encode this object to JSON * @@ -868,6 +893,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->customerDetails)) { $json['customer_details'] = $this->customerDetails; } + if (isset($this->offlinePaymentDetails)) { + $json['offline_payment_details'] = $this->offlinePaymentDetails; + } $json = array_filter($json, function ($val) { return $val !== null; }); diff --git a/src/Models/GiftCardActivityActivate.php b/src/Models/GiftCardActivityActivate.php index 0b24a9c3..b81de1f7 100644 --- a/src/Models/GiftCardActivityActivate.php +++ b/src/Models/GiftCardActivityActivate.php @@ -203,6 +203,8 @@ public function unsetReferenceId(): void * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. * + * Each buyer payment instrument ID can contain a maximum of 255 characters. + * * @return string[]|null */ public function getBuyerPaymentInstrumentIds(): ?array @@ -225,6 +227,8 @@ public function getBuyerPaymentInstrumentIds(): ?array * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. * + * Each buyer payment instrument ID can contain a maximum of 255 characters. + * * @maps buyer_payment_instrument_ids * * @param string[]|null $buyerPaymentInstrumentIds @@ -245,6 +249,8 @@ public function setBuyerPaymentInstrumentIds(?array $buyerPaymentInstrumentIds): * * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. + * + * Each buyer payment instrument ID can contain a maximum of 255 characters. */ public function unsetBuyerPaymentInstrumentIds(): void { diff --git a/src/Models/GiftCardActivityLoad.php b/src/Models/GiftCardActivityLoad.php index 85217d2a..a8af2519 100644 --- a/src/Models/GiftCardActivityLoad.php +++ b/src/Models/GiftCardActivityLoad.php @@ -210,6 +210,8 @@ public function unsetReferenceId(): void * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. * + * Each buyer payment instrument ID can contain a maximum of 255 characters. + * * @return string[]|null */ public function getBuyerPaymentInstrumentIds(): ?array @@ -233,6 +235,8 @@ public function getBuyerPaymentInstrumentIds(): ?array * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. * + * Each buyer payment instrument ID can contain a maximum of 255 characters. + * * @maps buyer_payment_instrument_ids * * @param string[]|null $buyerPaymentInstrumentIds @@ -254,6 +258,8 @@ public function setBuyerPaymentInstrumentIds(?array $buyerPaymentInstrumentIds): * * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. + * + * Each buyer payment instrument ID can contain a maximum of 255 characters. */ public function unsetBuyerPaymentInstrumentIds(): void { diff --git a/src/Models/GiftCardActivityRefund.php b/src/Models/GiftCardActivityRefund.php index 81918f3a..1442e391 100644 --- a/src/Models/GiftCardActivityRefund.php +++ b/src/Models/GiftCardActivityRefund.php @@ -35,8 +35,7 @@ class GiftCardActivityRefund implements \JsonSerializable * Returns Redeem Activity Id. * The ID of the refunded `REDEEM` gift card activity. Square populates this field if the * `payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request - * represents a redemption made by the same gift card. Note that you must use `RefundPayment` - * to refund a gift card payment to the same gift card if the payment was processed by Square. + * represents a gift card redemption. * * For applications that use a custom payment processing system, this field is required when creating * a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. @@ -53,8 +52,7 @@ public function getRedeemActivityId(): ?string * Sets Redeem Activity Id. * The ID of the refunded `REDEEM` gift card activity. Square populates this field if the * `payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request - * represents a redemption made by the same gift card. Note that you must use `RefundPayment` - * to refund a gift card payment to the same gift card if the payment was processed by Square. + * represents a gift card redemption. * * For applications that use a custom payment processing system, this field is required when creating * a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. @@ -70,8 +68,7 @@ public function setRedeemActivityId(?string $redeemActivityId): void * Unsets Redeem Activity Id. * The ID of the refunded `REDEEM` gift card activity. Square populates this field if the * `payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request - * represents a redemption made by the same gift card. Note that you must use `RefundPayment` - * to refund a gift card payment to the same gift card if the payment was processed by Square. + * represents a gift card redemption. * * For applications that use a custom payment processing system, this field is required when creating * a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. @@ -148,12 +145,8 @@ public function unsetReferenceId(): void /** * Returns Payment Id. * The ID of the refunded payment. Square populates this field if the refund is for a - * payment processed by Square and one of the following conditions is true: - * - * - The Refunds API is used to refund a gift card payment to the same gift card. - * - A seller initiated the refund from Square Point of Sale or the Seller Dashboard. The payment - * source can be the - * same gift card or a cross-tender payment from a credit card or a different gift card. + * payment processed by Square. This field matches the `payment_id` in the corresponding + * [RefundPayment](api-endpoint:Refunds-RefundPayment) request. */ public function getPaymentId(): ?string { @@ -163,12 +156,8 @@ public function getPaymentId(): ?string /** * Sets Payment Id. * The ID of the refunded payment. Square populates this field if the refund is for a - * payment processed by Square and one of the following conditions is true: - * - * - The Refunds API is used to refund a gift card payment to the same gift card. - * - A seller initiated the refund from Square Point of Sale or the Seller Dashboard. The payment - * source can be the - * same gift card or a cross-tender payment from a credit card or a different gift card. + * payment processed by Square. This field matches the `payment_id` in the corresponding + * [RefundPayment](api-endpoint:Refunds-RefundPayment) request. * * @maps payment_id */ diff --git a/src/Models/GiftCardActivityType.php b/src/Models/GiftCardActivityType.php index 0f7a9db3..d76a375e 100644 --- a/src/Models/GiftCardActivityType.php +++ b/src/Models/GiftCardActivityType.php @@ -49,13 +49,10 @@ class GiftCardActivityType /** * Added money to a gift card from a refunded transaction. A `REFUND` activity 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 using Square Point - * of Sale, - * the Square Seller Dashboard, or the Refunds API. - * - A cross-tender payment processed by Square can be refunded to a gift card using Square Point of - * Sale or the - * Square Seller Dashboard. The payment source might be a credit card or different gift card. - * - A payment processed using a custom payment processing system can be refunded to the same gift card. + * - A payment processed by Square can be refunded to a `PENDING` or `ACTIVE` gift card using the + * Square + * Seller Dashboard, Square Point of Sale, or Refunds API. + * - A payment processed using a custom processing system can be refunded to the same gift card. */ public const REFUND = 'REFUND'; diff --git a/src/Models/GiftCardStatus.php b/src/Models/GiftCardStatus.php index 108fa738..9abadabb 100644 --- a/src/Models/GiftCardStatus.php +++ b/src/Models/GiftCardStatus.php @@ -26,8 +26,9 @@ class GiftCardStatus /** * The gift card is pending activation. - * This is the initial state when a gift card is created. You must activate the gift card - * before it can be used. + * This is the initial state when a gift card is created. Typically, you'll call + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) to create an + * `ACTIVATE` activity that activates the gift card with an initial balance before first use. */ public const PENDING = 'PENDING'; } diff --git a/src/Models/ListPaymentsRequest.php b/src/Models/ListPaymentsRequest.php index ddbdf5b4..0e3d423f 100644 --- a/src/Models/ListPaymentsRequest.php +++ b/src/Models/ListPaymentsRequest.php @@ -59,6 +59,21 @@ class ListPaymentsRequest implements \JsonSerializable */ private $limit = []; + /** + * @var array + */ + private $isOfflinePayment = []; + + /** + * @var array + */ + private $offlineBeginTime = []; + + /** + * @var array + */ + private $offlineEndTime = []; + /** * Returns Begin Time. * Indicates the start of the time range to retrieve payments for, in RFC 3339 format. @@ -401,6 +416,132 @@ public function unsetLimit(): void $this->limit = []; } + /** + * Returns Is Offline Payment. + * Whether the payment was taken offline or not. + */ + public function getIsOfflinePayment(): ?bool + { + if (count($this->isOfflinePayment) == 0) { + return null; + } + return $this->isOfflinePayment['value']; + } + + /** + * Sets Is Offline Payment. + * Whether the payment was taken offline or not. + * + * @maps is_offline_payment + */ + public function setIsOfflinePayment(?bool $isOfflinePayment): void + { + $this->isOfflinePayment['value'] = $isOfflinePayment; + } + + /** + * Unsets Is Offline Payment. + * Whether the payment was taken offline or not. + */ + public function unsetIsOfflinePayment(): void + { + $this->isOfflinePayment = []; + } + + /** + * Returns Offline Begin Time. + * Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. + */ + public function getOfflineBeginTime(): ?string + { + if (count($this->offlineBeginTime) == 0) { + return null; + } + return $this->offlineBeginTime['value']; + } + + /** + * Sets Offline Begin Time. + * Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. + * + * @maps offline_begin_time + */ + public function setOfflineBeginTime(?string $offlineBeginTime): void + { + $this->offlineBeginTime['value'] = $offlineBeginTime; + } + + /** + * Unsets Offline Begin Time. + * Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. + */ + public function unsetOfflineBeginTime(): void + { + $this->offlineBeginTime = []; + } + + /** + * Returns Offline End Time. + * Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. + */ + public function getOfflineEndTime(): ?string + { + if (count($this->offlineEndTime) == 0) { + return null; + } + return $this->offlineEndTime['value']; + } + + /** + * Sets Offline End Time. + * Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. + * + * @maps offline_end_time + */ + public function setOfflineEndTime(?string $offlineEndTime): void + { + $this->offlineEndTime['value'] = $offlineEndTime; + } + + /** + * Unsets Offline End Time. + * Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * + * Default: The current time. + */ + public function unsetOfflineEndTime(): void + { + $this->offlineEndTime = []; + } + /** * Encode this object to JSON * @@ -414,31 +555,40 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) { $json = []; if (!empty($this->beginTime)) { - $json['begin_time'] = $this->beginTime['value']; + $json['begin_time'] = $this->beginTime['value']; } if (!empty($this->endTime)) { - $json['end_time'] = $this->endTime['value']; + $json['end_time'] = $this->endTime['value']; } if (!empty($this->sortOrder)) { - $json['sort_order'] = $this->sortOrder['value']; + $json['sort_order'] = $this->sortOrder['value']; } if (!empty($this->cursor)) { - $json['cursor'] = $this->cursor['value']; + $json['cursor'] = $this->cursor['value']; } if (!empty($this->locationId)) { - $json['location_id'] = $this->locationId['value']; + $json['location_id'] = $this->locationId['value']; } if (!empty($this->total)) { - $json['total'] = $this->total['value']; + $json['total'] = $this->total['value']; } if (!empty($this->last4)) { - $json['last_4'] = $this->last4['value']; + $json['last_4'] = $this->last4['value']; } if (!empty($this->cardBrand)) { - $json['card_brand'] = $this->cardBrand['value']; + $json['card_brand'] = $this->cardBrand['value']; } if (!empty($this->limit)) { - $json['limit'] = $this->limit['value']; + $json['limit'] = $this->limit['value']; + } + if (!empty($this->isOfflinePayment)) { + $json['is_offline_payment'] = $this->isOfflinePayment['value']; + } + if (!empty($this->offlineBeginTime)) { + $json['offline_begin_time'] = $this->offlineBeginTime['value']; + } + if (!empty($this->offlineEndTime)) { + $json['offline_end_time'] = $this->offlineEndTime['value']; } $json = array_filter($json, function ($val) { return $val !== null; diff --git a/src/Models/OfflinePaymentDetails.php b/src/Models/OfflinePaymentDetails.php new file mode 100644 index 00000000..28ba052f --- /dev/null +++ b/src/Models/OfflinePaymentDetails.php @@ -0,0 +1,60 @@ +clientCreatedAt; + } + + /** + * Sets Client Created At. + * The client-side timestamp of when the offline payment was created, in RFC 3339 format. + * + * @maps client_created_at + */ + public function setClientCreatedAt(?string $clientCreatedAt): void + { + $this->clientCreatedAt = $clientCreatedAt; + } + + /** + * 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->clientCreatedAt)) { + $json['client_created_at'] = $this->clientCreatedAt; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/Payment.php b/src/Models/Payment.php index 77ab39ed..11f4aea0 100644 --- a/src/Models/Payment.php +++ b/src/Models/Payment.php @@ -147,9 +147,9 @@ class Payment implements \JsonSerializable private $employeeId; /** - * @var string|null + * @var array */ - private $teamMemberId; + private $teamMemberId = []; /** * @var string[]|null @@ -216,6 +216,11 @@ class Payment implements \JsonSerializable */ private $isOfflinePayment; + /** + * @var OfflinePaymentDetails|null + */ + private $offlinePaymentDetails; + /** * @var array */ @@ -945,7 +950,10 @@ public function setEmployeeId(?string $employeeId): void */ public function getTeamMemberId(): ?string { - return $this->teamMemberId; + if (count($this->teamMemberId) == 0) { + return null; + } + return $this->teamMemberId['value']; } /** @@ -956,7 +964,16 @@ public function getTeamMemberId(): ?string */ public function setTeamMemberId(?string $teamMemberId): void { - $this->teamMemberId = $teamMemberId; + $this->teamMemberId['value'] = $teamMemberId; + } + + /** + * Unsets Team Member Id. + * An optional ID of the [TeamMember](entity:TeamMember) associated with taking the payment. + */ + public function unsetTeamMemberId(): void + { + $this->teamMemberId = []; } /** @@ -1269,6 +1286,26 @@ public function setIsOfflinePayment(?bool $isOfflinePayment): void $this->isOfflinePayment = $isOfflinePayment; } + /** + * Returns Offline Payment Details. + * Details specific to offline payments. + */ + public function getOfflinePaymentDetails(): ?OfflinePaymentDetails + { + return $this->offlinePaymentDetails; + } + + /** + * Sets Offline Payment Details. + * Details specific to offline payments. + * + * @maps offline_payment_details + */ + public function setOfflinePaymentDetails(?OfflinePaymentDetails $offlinePaymentDetails): void + { + $this->offlinePaymentDetails = $offlinePaymentDetails; + } + /** * Returns Version Token. * Used for optimistic concurrency. This opaque token identifies a specific version of the @@ -1397,8 +1434,8 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->employeeId)) { $json['employee_id'] = $this->employeeId; } - if (isset($this->teamMemberId)) { - $json['team_member_id'] = $this->teamMemberId; + if (!empty($this->teamMemberId)) { + $json['team_member_id'] = $this->teamMemberId['value']; } if (isset($this->refundIds)) { $json['refund_ids'] = $this->refundIds; @@ -1439,6 +1476,9 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (isset($this->isOfflinePayment)) { $json['is_offline_payment'] = $this->isOfflinePayment; } + if (isset($this->offlinePaymentDetails)) { + $json['offline_payment_details'] = $this->offlinePaymentDetails; + } if (!empty($this->versionToken)) { $json['version_token'] = $this->versionToken['value']; } diff --git a/src/SquareClient.php b/src/SquareClient.php index 11478ae6..3049744e 100644 --- a/src/SquareClient.php +++ b/src/SquareClient.php @@ -165,7 +165,7 @@ public function __construct(array $config = []) ->jsonHelper(ApiHelper::getJsonHelper()) ->apiCallback($this->config['httpCallback'] ?? null) ->userAgent( - 'Square-PHP-SDK/37.1.1.20240717 ({api-version}) {engine}/{engine-version} ({os-' . + 'Square-PHP-SDK/38.0.0.20240821 ({api-version}) {engine}/{engine-version} ({os-' . 'info}) {detail}' ) ->userAgentConfig( @@ -320,7 +320,7 @@ public function withConfiguration(array $config): self */ public function getSdkVersion(): string { - return '37.1.1.20240717'; + return '38.0.0.20240821'; } /**