diff --git a/composer.json b/composer.json index 2f3765a1..367e03b8 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": "38.1.0.20240919", + "version": "38.2.0.20241017", "type": "library", "keywords": [ "Square", diff --git a/doc/client.md b/doc/client.md index 7319159e..9dcd3ad6 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-09-19'` | +| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2024-10-17'` | | `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-09-19') + ->squareVersion('2024-10-17') ->environment(Environment::PRODUCTION) ->customUrl('https://connect.squareup.com') ->build(); @@ -61,7 +61,7 @@ $client = SquareClientBuilder::init() 'AccessToken' ) ) - ->squareVersion('2024-09-19') + ->squareVersion('2024-10-17') ->environment(Environment::PRODUCTION) ->customUrl('https://connect.squareup.com') ->build(); diff --git a/doc/models/destination-details-cash-refund-details.md b/doc/models/destination-details-cash-refund-details.md new file mode 100644 index 00000000..ab73439f --- /dev/null +++ b/doc/models/destination-details-cash-refund-details.md @@ -0,0 +1,31 @@ + +# Destination Details Cash Refund Details + +Stores details about a cash refund. Contains only non-confidential information. + +## Structure + +`DestinationDetailsCashRefundDetails` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `sellerSuppliedMoney` | [`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. | getSellerSuppliedMoney(): Money | setSellerSuppliedMoney(Money sellerSuppliedMoney): void | +| `changeBackMoney` | [`?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. | getChangeBackMoney(): ?Money | setChangeBackMoney(?Money changeBackMoney): void | + +## Example (as JSON) + +```json +{ + "seller_supplied_money": { + "amount": 36, + "currency": "AZN" + }, + "change_back_money": { + "amount": 78, + "currency": "DJF" + } +} +``` + diff --git a/doc/models/destination-details-external-refund-details.md b/doc/models/destination-details-external-refund-details.md new file mode 100644 index 00000000..7ad3bfe7 --- /dev/null +++ b/doc/models/destination-details-external-refund-details.md @@ -0,0 +1,27 @@ + +# Destination Details External Refund Details + +Stores details about an external refund. Contains only non-confidential information. + +## Structure + +`DestinationDetailsExternalRefundDetails` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `type` | `string` | Required | The type of external refund the seller paid to the buyer. It can be one of the
following:

- CHECK - Refunded using a physical check.
- BANK_TRANSFER - Refunded using external bank transfer.
- OTHER\_GIFT\_CARD - Refunded using a non-Square gift card.
- CRYPTO - Refunded using a crypto currency.
- SQUARE_CASH - Refunded using Square Cash App.
- SOCIAL - Refunded using peer-to-peer payment applications.
- EXTERNAL - A third-party application gathered this refund outside of Square.
- EMONEY - Refunded using an E-money provider.
- CARD - A credit or debit card that Square does not support.
- STORED_BALANCE - Use for house accounts, store credit, and so forth.
- FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals
- OTHER - A type not listed here.
**Constraints**: *Maximum Length*: `50` | getType(): string | setType(string type): void | +| `source` | `string` | Required | A description of the external refund source. For example,
"Food Delivery Service".
**Constraints**: *Maximum Length*: `255` | getSource(): string | setSource(string source): void | +| `sourceId` | `?string` | Optional | An ID to associate the refund to its originating source.
**Constraints**: *Maximum Length*: `255` | getSourceId(): ?string | setSourceId(?string sourceId): void | + +## Example (as JSON) + +```json +{ + "type": "type4", + "source": "source2", + "source_id": "source_id0" +} +``` + diff --git a/doc/models/destination-details.md b/doc/models/destination-details.md index 3e00adf6..c85435b8 100644 --- a/doc/models/destination-details.md +++ b/doc/models/destination-details.md @@ -12,6 +12,8 @@ Details about a refund's destination. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `cardDetails` | [`?DestinationDetailsCardRefundDetails`](../../doc/models/destination-details-card-refund-details.md) | Optional | - | getCardDetails(): ?DestinationDetailsCardRefundDetails | setCardDetails(?DestinationDetailsCardRefundDetails cardDetails): void | +| `cashDetails` | [`?DestinationDetailsCashRefundDetails`](../../doc/models/destination-details-cash-refund-details.md) | Optional | Stores details about a cash refund. Contains only non-confidential information. | getCashDetails(): ?DestinationDetailsCashRefundDetails | setCashDetails(?DestinationDetailsCashRefundDetails cashDetails): void | +| `externalDetails` | [`?DestinationDetailsExternalRefundDetails`](../../doc/models/destination-details-external-refund-details.md) | Optional | Stores details about an external refund. Contains only non-confidential information. | getExternalDetails(): ?DestinationDetailsExternalRefundDetails | setExternalDetails(?DestinationDetailsExternalRefundDetails externalDetails): void | ## Example (as JSON) @@ -27,6 +29,21 @@ Details about a refund's destination. }, "entry_method": "entry_method8", "auth_result_code": "auth_result_code0" + }, + "cash_details": { + "seller_supplied_money": { + "amount": 36, + "currency": "AZN" + }, + "change_back_money": { + "amount": 78, + "currency": "DJF" + } + }, + "external_details": { + "type": "type6", + "source": "source0", + "source_id": "source_id8" } } ``` diff --git a/doc/models/get-payment-refund-response.md b/doc/models/get-payment-refund-response.md index 013707c9..6f1966d5 100644 --- a/doc/models/get-payment-refund-response.md +++ b/doc/models/get-payment-refund-response.md @@ -57,6 +57,21 @@ present or it might be present in a FAILED state. }, "entry_method": "entry_method8", "auth_result_code": "auth_result_code0" + }, + "cash_details": { + "seller_supplied_money": { + "amount": 36, + "currency": "AZN" + }, + "change_back_money": { + "amount": 78, + "currency": "DJF" + } + }, + "external_details": { + "type": "type6", + "source": "source0", + "source_id": "source_id8" } } }, diff --git a/doc/models/list-payment-refunds-response.md b/doc/models/list-payment-refunds-response.md index cf248e70..8d6a51d3 100644 --- a/doc/models/list-payment-refunds-response.md +++ b/doc/models/list-payment-refunds-response.md @@ -59,6 +59,21 @@ Either `errors` or `refunds` is present in a given response (never both). }, "entry_method": "entry_method8", "auth_result_code": "auth_result_code0" + }, + "cash_details": { + "seller_supplied_money": { + "amount": 36, + "currency": "AZN" + }, + "change_back_money": { + "amount": 78, + "currency": "DJF" + } + }, + "external_details": { + "type": "type6", + "source": "source0", + "source_id": "source_id8" } } } diff --git a/doc/models/payment-refund.md b/doc/models/payment-refund.md index ffc5aa9e..3c531f69 100644 --- a/doc/models/payment-refund.md +++ b/doc/models/payment-refund.md @@ -48,6 +48,21 @@ the original payment and the amount of money refunded. }, "entry_method": "entry_method8", "auth_result_code": "auth_result_code0" + }, + "cash_details": { + "seller_supplied_money": { + "amount": 36, + "currency": "AZN" + }, + "change_back_money": { + "amount": 78, + "currency": "DJF" + } + }, + "external_details": { + "type": "type6", + "source": "source0", + "source_id": "source_id8" } }, "amount_money": { diff --git a/doc/models/refund-payment-request.md b/doc/models/refund-payment-request.md index eb9de170..8a2ae901 100644 --- a/doc/models/refund-payment-request.md +++ b/doc/models/refund-payment-request.md @@ -15,13 +15,15 @@ Describes a request to refund a payment using [RefundPayment](../../doc/apis/ref | `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 | | `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 | | `paymentId` | `?string` | Optional | The unique ID of the payment being refunded.
Required when unlinked=false, otherwise must not be set. | getPaymentId(): ?string | setPaymentId(?string paymentId): void | -| `destinationId` | `?string` | Optional | The ID indicating where funds will be refunded to, if this is an unlinked refund.
This can be any of the following: A token generated by Web Payments SDK;
a card-on-file identifier.
Required for requests specifying unlinked=true.
Otherwise, if included when `unlinked=false`, will throw an error. | getDestinationId(): ?string | setDestinationId(?string destinationId): void | +| `destinationId` | `?string` | Optional | The ID indicating where funds will be refunded to. Required for unlinked refunds. For more
information, see [Create an unlinked refund](https://developer.squareup.com/docs/payments-api/refund-payments#create-an-unlinked-refund).

For refunds linked to Square payments, destination_id is usually omitted; in this case, funds
will be returned to the original payment source. The field may be specified in order to request
a cross-method refund to a gift card. For more information,
see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund-payments#cross-method-refunds-to-gift-cards). | getDestinationId(): ?string | setDestinationId(?string destinationId): void | | `unlinked` | `?bool` | Optional | Indicates that the refund is not linked to a Square payment.
If set to true, `destination_id` and `location_id` must be supplied while `payment_id` must not
be provided. | getUnlinked(): ?bool | setUnlinked(?bool unlinked): void | | `locationId` | `?string` | Optional | The location ID associated with the unlinked refund.
Required for requests specifying `unlinked=true`.
Otherwise, if included when `unlinked=false`, will throw an error.
**Constraints**: *Maximum Length*: `50` | getLocationId(): ?string | setLocationId(?string locationId): void | | `customerId` | `?string` | Optional | The [Customer](entity:Customer) ID of the customer associated with the refund.
This is required if the `destination_id` refers to a card on file created using the Cards
API. Only allowed when `unlinked=true`. | getCustomerId(): ?string | setCustomerId(?string customerId): void | | `reason` | `?string` | Optional | A description of the reason for the refund.
**Constraints**: *Maximum Length*: `192` | getReason(): ?string | setReason(?string reason): void | | `paymentVersionToken` | `?string` | Optional | Used for optimistic concurrency. This opaque token identifies the current `Payment`
version that the caller expects. If the server has a different version of the Payment,
the update fails and a response with a VERSION_MISMATCH error is returned.
If the versions match, or the field is not provided, the refund proceeds as normal. | getPaymentVersionToken(): ?string | setPaymentVersionToken(?string paymentVersionToken): void | | `teamMemberId` | `?string` | Optional | An optional [TeamMember](entity:TeamMember) ID to associate with this refund.
**Constraints**: *Maximum Length*: `192` | getTeamMemberId(): ?string | setTeamMemberId(?string teamMemberId): void | +| `cashDetails` | [`?DestinationDetailsCashRefundDetails`](../../doc/models/destination-details-cash-refund-details.md) | Optional | Stores details about a cash refund. Contains only non-confidential information. | getCashDetails(): ?DestinationDetailsCashRefundDetails | setCashDetails(?DestinationDetailsCashRefundDetails cashDetails): void | +| `externalDetails` | [`?DestinationDetailsExternalRefundDetails`](../../doc/models/destination-details-external-refund-details.md) | Optional | Stores details about an external refund. Contains only non-confidential information. | getExternalDetails(): ?DestinationDetailsExternalRefundDetails | setExternalDetails(?DestinationDetailsExternalRefundDetails externalDetails): void | ## Example (as JSON) diff --git a/doc/models/refund-payment-response.md b/doc/models/refund-payment-response.md index cb7b5bc5..bd281afb 100644 --- a/doc/models/refund-payment-response.md +++ b/doc/models/refund-payment-response.md @@ -52,6 +52,21 @@ present, or it might be present with a status of `FAILED`. }, "entry_method": "entry_method8", "auth_result_code": "auth_result_code0" + }, + "cash_details": { + "seller_supplied_money": { + "amount": 36, + "currency": "AZN" + }, + "change_back_money": { + "amount": 78, + "currency": "DJF" + } + }, + "external_details": { + "type": "type6", + "source": "source0", + "source_id": "source_id8" } } }, diff --git a/src/ConfigurationDefaults.php b/src/ConfigurationDefaults.php index 0781c8ad..5c976631 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-09-19'; + public const SQUARE_VERSION = '2024-10-17'; public const ADDITIONAL_HEADERS = []; diff --git a/src/Models/Builders/DestinationDetailsBuilder.php b/src/Models/Builders/DestinationDetailsBuilder.php index 2bd3dad5..b463e03d 100644 --- a/src/Models/Builders/DestinationDetailsBuilder.php +++ b/src/Models/Builders/DestinationDetailsBuilder.php @@ -7,6 +7,8 @@ use Core\Utils\CoreHelper; use Square\Models\DestinationDetails; use Square\Models\DestinationDetailsCardRefundDetails; +use Square\Models\DestinationDetailsCashRefundDetails; +use Square\Models\DestinationDetailsExternalRefundDetails; /** * Builder for model DestinationDetails @@ -42,6 +44,24 @@ public function cardDetails(?DestinationDetailsCardRefundDetails $value): self return $this; } + /** + * Sets cash details field. + */ + public function cashDetails(?DestinationDetailsCashRefundDetails $value): self + { + $this->instance->setCashDetails($value); + return $this; + } + + /** + * Sets external details field. + */ + public function externalDetails(?DestinationDetailsExternalRefundDetails $value): self + { + $this->instance->setExternalDetails($value); + return $this; + } + /** * Initializes a new destination details object. */ diff --git a/src/Models/Builders/DestinationDetailsCashRefundDetailsBuilder.php b/src/Models/Builders/DestinationDetailsCashRefundDetailsBuilder.php new file mode 100644 index 00000000..49420d1f --- /dev/null +++ b/src/Models/Builders/DestinationDetailsCashRefundDetailsBuilder.php @@ -0,0 +1,52 @@ +instance = $instance; + } + + /** + * Initializes a new destination details cash refund details Builder object. + */ + public static function init(Money $sellerSuppliedMoney): self + { + return new self(new DestinationDetailsCashRefundDetails($sellerSuppliedMoney)); + } + + /** + * Sets change back money field. + */ + public function changeBackMoney(?Money $value): self + { + $this->instance->setChangeBackMoney($value); + return $this; + } + + /** + * Initializes a new destination details cash refund details object. + */ + public function build(): DestinationDetailsCashRefundDetails + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/DestinationDetailsExternalRefundDetailsBuilder.php b/src/Models/Builders/DestinationDetailsExternalRefundDetailsBuilder.php new file mode 100644 index 00000000..d0d189c6 --- /dev/null +++ b/src/Models/Builders/DestinationDetailsExternalRefundDetailsBuilder.php @@ -0,0 +1,60 @@ +instance = $instance; + } + + /** + * Initializes a new destination details external refund details Builder object. + */ + public static function init(string $type, string $source): self + { + return new self(new DestinationDetailsExternalRefundDetails($type, $source)); + } + + /** + * Sets source id field. + */ + public function sourceId(?string $value): self + { + $this->instance->setSourceId($value); + return $this; + } + + /** + * Unsets source id field. + */ + public function unsetSourceId(): self + { + $this->instance->unsetSourceId(); + return $this; + } + + /** + * Initializes a new destination details external refund details object. + */ + public function build(): DestinationDetailsExternalRefundDetails + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/RefundPaymentRequestBuilder.php b/src/Models/Builders/RefundPaymentRequestBuilder.php index 155d3430..ef8f1b60 100644 --- a/src/Models/Builders/RefundPaymentRequestBuilder.php +++ b/src/Models/Builders/RefundPaymentRequestBuilder.php @@ -5,6 +5,8 @@ namespace Square\Models\Builders; use Core\Utils\CoreHelper; +use Square\Models\DestinationDetailsCashRefundDetails; +use Square\Models\DestinationDetailsExternalRefundDetails; use Square\Models\Money; use Square\Models\RefundPaymentRequest; @@ -186,6 +188,24 @@ public function unsetTeamMemberId(): self return $this; } + /** + * Sets cash details field. + */ + public function cashDetails(?DestinationDetailsCashRefundDetails $value): self + { + $this->instance->setCashDetails($value); + return $this; + } + + /** + * Sets external details field. + */ + public function externalDetails(?DestinationDetailsExternalRefundDetails $value): self + { + $this->instance->setExternalDetails($value); + return $this; + } + /** * Initializes a new refund payment request object. */ diff --git a/src/Models/DestinationDetails.php b/src/Models/DestinationDetails.php index 4f80a0a4..61836b74 100644 --- a/src/Models/DestinationDetails.php +++ b/src/Models/DestinationDetails.php @@ -16,6 +16,16 @@ class DestinationDetails implements \JsonSerializable */ private $cardDetails; + /** + * @var DestinationDetailsCashRefundDetails|null + */ + private $cashDetails; + + /** + * @var DestinationDetailsExternalRefundDetails|null + */ + private $externalDetails; + /** * Returns Card Details. */ @@ -34,6 +44,46 @@ public function setCardDetails(?DestinationDetailsCardRefundDetails $cardDetails $this->cardDetails = $cardDetails; } + /** + * Returns Cash Details. + * Stores details about a cash refund. Contains only non-confidential information. + */ + public function getCashDetails(): ?DestinationDetailsCashRefundDetails + { + return $this->cashDetails; + } + + /** + * Sets Cash Details. + * Stores details about a cash refund. Contains only non-confidential information. + * + * @maps cash_details + */ + public function setCashDetails(?DestinationDetailsCashRefundDetails $cashDetails): void + { + $this->cashDetails = $cashDetails; + } + + /** + * Returns External Details. + * Stores details about an external refund. Contains only non-confidential information. + */ + public function getExternalDetails(): ?DestinationDetailsExternalRefundDetails + { + return $this->externalDetails; + } + + /** + * Sets External Details. + * Stores details about an external refund. Contains only non-confidential information. + * + * @maps external_details + */ + public function setExternalDetails(?DestinationDetailsExternalRefundDetails $externalDetails): void + { + $this->externalDetails = $externalDetails; + } + /** * Encode this object to JSON * @@ -47,7 +97,13 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) { $json = []; if (isset($this->cardDetails)) { - $json['card_details'] = $this->cardDetails; + $json['card_details'] = $this->cardDetails; + } + if (isset($this->cashDetails)) { + $json['cash_details'] = $this->cashDetails; + } + if (isset($this->externalDetails)) { + $json['external_details'] = $this->externalDetails; } $json = array_filter($json, function ($val) { return $val !== null; diff --git a/src/Models/DestinationDetailsCashRefundDetails.php b/src/Models/DestinationDetailsCashRefundDetails.php new file mode 100644 index 00000000..90f1460a --- /dev/null +++ b/src/Models/DestinationDetailsCashRefundDetails.php @@ -0,0 +1,119 @@ +sellerSuppliedMoney = $sellerSuppliedMoney; + } + + /** + * Returns Seller Supplied Money. + * 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. + */ + public function getSellerSuppliedMoney(): Money + { + return $this->sellerSuppliedMoney; + } + + /** + * Sets Seller Supplied Money. + * 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. + * + * @required + * @maps seller_supplied_money + */ + public function setSellerSuppliedMoney(Money $sellerSuppliedMoney): void + { + $this->sellerSuppliedMoney = $sellerSuppliedMoney; + } + + /** + * Returns Change Back Money. + * 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. + */ + public function getChangeBackMoney(): ?Money + { + return $this->changeBackMoney; + } + + /** + * Sets Change Back Money. + * 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. + * + * @maps change_back_money + */ + public function setChangeBackMoney(?Money $changeBackMoney): void + { + $this->changeBackMoney = $changeBackMoney; + } + + /** + * 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 = []; + $json['seller_supplied_money'] = $this->sellerSuppliedMoney; + if (isset($this->changeBackMoney)) { + $json['change_back_money'] = $this->changeBackMoney; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/DestinationDetailsExternalRefundDetails.php b/src/Models/DestinationDetailsExternalRefundDetails.php new file mode 100644 index 00000000..636d4954 --- /dev/null +++ b/src/Models/DestinationDetailsExternalRefundDetails.php @@ -0,0 +1,164 @@ +type = $type; + $this->source = $source; + } + + /** + * Returns Type. + * The type of external refund the seller paid to the buyer. It can be one of the + * following: + * - CHECK - Refunded using a physical check. + * - BANK_TRANSFER - Refunded using external bank transfer. + * - OTHER\_GIFT\_CARD - Refunded using a non-Square gift card. + * - CRYPTO - Refunded using a crypto currency. + * - SQUARE_CASH - Refunded using Square Cash App. + * - SOCIAL - Refunded using peer-to-peer payment applications. + * - EXTERNAL - A third-party application gathered this refund outside of Square. + * - EMONEY - Refunded using an E-money provider. + * - CARD - A credit or debit card that Square does not support. + * - STORED_BALANCE - Use for house accounts, store credit, and so forth. + * - FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals + * - OTHER - A type not listed here. + */ + public function getType(): string + { + return $this->type; + } + + /** + * Sets Type. + * The type of external refund the seller paid to the buyer. It can be one of the + * following: + * - CHECK - Refunded using a physical check. + * - BANK_TRANSFER - Refunded using external bank transfer. + * - OTHER\_GIFT\_CARD - Refunded using a non-Square gift card. + * - CRYPTO - Refunded using a crypto currency. + * - SQUARE_CASH - Refunded using Square Cash App. + * - SOCIAL - Refunded using peer-to-peer payment applications. + * - EXTERNAL - A third-party application gathered this refund outside of Square. + * - EMONEY - Refunded using an E-money provider. + * - CARD - A credit or debit card that Square does not support. + * - STORED_BALANCE - Use for house accounts, store credit, and so forth. + * - FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals + * - OTHER - A type not listed here. + * + * @required + * @maps type + */ + public function setType(string $type): void + { + $this->type = $type; + } + + /** + * Returns Source. + * A description of the external refund source. For example, + * "Food Delivery Service". + */ + public function getSource(): string + { + return $this->source; + } + + /** + * Sets Source. + * A description of the external refund source. For example, + * "Food Delivery Service". + * + * @required + * @maps source + */ + public function setSource(string $source): void + { + $this->source = $source; + } + + /** + * Returns Source Id. + * An ID to associate the refund to its originating source. + */ + public function getSourceId(): ?string + { + if (count($this->sourceId) == 0) { + return null; + } + return $this->sourceId['value']; + } + + /** + * Sets Source Id. + * An ID to associate the refund to its originating source. + * + * @maps source_id + */ + public function setSourceId(?string $sourceId): void + { + $this->sourceId['value'] = $sourceId; + } + + /** + * Unsets Source Id. + * An ID to associate the refund to its originating source. + */ + public function unsetSourceId(): void + { + $this->sourceId = []; + } + + /** + * 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 = []; + $json['type'] = $this->type; + $json['source'] = $this->source; + if (!empty($this->sourceId)) { + $json['source_id'] = $this->sourceId['value']; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/RefundPaymentRequest.php b/src/Models/RefundPaymentRequest.php index cfbe4c1f..45372872 100644 --- a/src/Models/RefundPaymentRequest.php +++ b/src/Models/RefundPaymentRequest.php @@ -66,6 +66,16 @@ class RefundPaymentRequest implements \JsonSerializable */ private $teamMemberId = []; + /** + * @var DestinationDetailsCashRefundDetails|null + */ + private $cashDetails; + + /** + * @var DestinationDetailsExternalRefundDetails|null + */ + private $externalDetails; + /** * @param string $idempotencyKey * @param Money $amountMoney @@ -213,11 +223,15 @@ public function unsetPaymentId(): void /** * Returns Destination Id. - * The ID indicating where funds will be refunded to, if this is an unlinked refund. - * This can be any of the following: A token generated by Web Payments SDK; - * a card-on-file identifier. - * Required for requests specifying unlinked=true. - * Otherwise, if included when `unlinked=false`, will throw an error. + * The ID indicating where funds will be refunded to. Required for unlinked refunds. For more + * information, see [Create an unlinked refund](https://developer.squareup.com/docs/payments-api/refund- + * payments#create-an-unlinked-refund). + * + * For refunds linked to Square payments, destination_id is usually omitted; in this case, funds + * will be returned to the original payment source. The field may be specified in order to request + * a cross-method refund to a gift card. For more information, + * see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund- + * payments#cross-method-refunds-to-gift-cards). */ public function getDestinationId(): ?string { @@ -229,11 +243,15 @@ public function getDestinationId(): ?string /** * Sets Destination Id. - * The ID indicating where funds will be refunded to, if this is an unlinked refund. - * This can be any of the following: A token generated by Web Payments SDK; - * a card-on-file identifier. - * Required for requests specifying unlinked=true. - * Otherwise, if included when `unlinked=false`, will throw an error. + * The ID indicating where funds will be refunded to. Required for unlinked refunds. For more + * information, see [Create an unlinked refund](https://developer.squareup.com/docs/payments-api/refund- + * payments#create-an-unlinked-refund). + * + * For refunds linked to Square payments, destination_id is usually omitted; in this case, funds + * will be returned to the original payment source. The field may be specified in order to request + * a cross-method refund to a gift card. For more information, + * see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund- + * payments#cross-method-refunds-to-gift-cards). * * @maps destination_id */ @@ -244,11 +262,15 @@ public function setDestinationId(?string $destinationId): void /** * Unsets Destination Id. - * The ID indicating where funds will be refunded to, if this is an unlinked refund. - * This can be any of the following: A token generated by Web Payments SDK; - * a card-on-file identifier. - * Required for requests specifying unlinked=true. - * Otherwise, if included when `unlinked=false`, will throw an error. + * The ID indicating where funds will be refunded to. Required for unlinked refunds. For more + * information, see [Create an unlinked refund](https://developer.squareup.com/docs/payments-api/refund- + * payments#create-an-unlinked-refund). + * + * For refunds linked to Square payments, destination_id is usually omitted; in this case, funds + * will be returned to the original payment source. The field may be specified in order to request + * a cross-method refund to a gift card. For more information, + * see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund- + * payments#cross-method-refunds-to-gift-cards). */ public function unsetDestinationId(): void { @@ -474,6 +496,46 @@ public function unsetTeamMemberId(): void $this->teamMemberId = []; } + /** + * Returns Cash Details. + * Stores details about a cash refund. Contains only non-confidential information. + */ + public function getCashDetails(): ?DestinationDetailsCashRefundDetails + { + return $this->cashDetails; + } + + /** + * Sets Cash Details. + * Stores details about a cash refund. Contains only non-confidential information. + * + * @maps cash_details + */ + public function setCashDetails(?DestinationDetailsCashRefundDetails $cashDetails): void + { + $this->cashDetails = $cashDetails; + } + + /** + * Returns External Details. + * Stores details about an external refund. Contains only non-confidential information. + */ + public function getExternalDetails(): ?DestinationDetailsExternalRefundDetails + { + return $this->externalDetails; + } + + /** + * Sets External Details. + * Stores details about an external refund. Contains only non-confidential information. + * + * @maps external_details + */ + public function setExternalDetails(?DestinationDetailsExternalRefundDetails $externalDetails): void + { + $this->externalDetails = $externalDetails; + } + /** * Encode this object to JSON * @@ -515,6 +577,12 @@ public function jsonSerialize(bool $asArrayWhenEmpty = false) if (!empty($this->teamMemberId)) { $json['team_member_id'] = $this->teamMemberId['value']; } + if (isset($this->cashDetails)) { + $json['cash_details'] = $this->cashDetails; + } + if (isset($this->externalDetails)) { + $json['external_details'] = $this->externalDetails; + } $json = array_filter($json, function ($val) { return $val !== null; }); diff --git a/src/SquareClient.php b/src/SquareClient.php index d6a9a6db..9f13e0ac 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/38.1.0.20240919 ({api-version}) {engine}/{engine-version} ({os-' . + 'Square-PHP-SDK/38.2.0.20241017 ({api-version}) {engine}/{engine-version} ({os-' . 'info}) {detail}' ) ->userAgentConfig( @@ -320,7 +320,7 @@ public function withConfiguration(array $config): self */ public function getSdkVersion(): string { - return '38.1.0.20240919'; + return '38.2.0.20241017'; } /**