chore: synced file(s) with sumup/apis

src/Checkouts/Checkouts.php

@@ -12,6 +12,40 @@
 use SumUp\ResponseDecoder;
 use SumUp\SdkInfo;
 
+class CheckoutsCreateApplePaySessionRequest
+{
+    /**
+     * the context to create this apple pay session.
+     *
+     * @var string
+     */
+    public string $context;
+
+    /**
+     * The target url to create this apple pay session.
+     *
+     * @var string
+     */
+    public string $target;
+
+    /**
+     * Create request DTO from an associative array.
+     *
+     * @param array<string, mixed> $data
+     */
+    public function __construct(array $data = [])
+    {
+        if ($data !== []) {
+            \SumUp\Hydrator::hydrate($data, self::class, $this);
+        }
+    }
+
+}
+
+class CheckoutsCreateApplePaySessionResponse
+{
+}
+
 class CheckoutsListAvailablePaymentMethodsResponse
 {
     /**
@@ -75,11 +109,20 @@ class CheckoutsListAvailablePaymentMethodsParams
 /**
  * Class Checkouts
  *
- * Accept payments from your end users by adding the Checkouts model to your platform.
- * SumUp supports standard and single payment 3DS checkout flows.
+ * Checkouts represent online payment sessions that you create before attempting to charge a payer. A checkout captures the payment intent, such as the amount, currency, merchant, and optional customer or redirect settings, and then moves through its lifecycle as you process it.
+ *
+ * Use this tag to:
+ * - create a checkout before collecting or confirming payment details
+ * - process the checkout with a card, saved card, wallet, or supported alternative payment method
+ * - retrieve or list checkouts to inspect their current state and associated payment attempts
+ * - deactivate a checkout that should no longer be used
+ *
+ * Typical workflow:
+ * - create a checkout with the order amount, currency, and merchant information
+ * - process the checkout through SumUp client tools such as the [Payment Widget and Swift Checkout SDK](https://developer.sumup.com/online-payments/checkouts)
+ * - retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record
  *
- * The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts.
- * A payment is completed by creating a checkout and then processing the checkout.
+ * Checkouts are used to initiate and orchestrate online payments. Transactions remain the authoritative record of the resulting payment outcome.
  *
  * @package SumUp\Services
  */
@@ -144,6 +187,38 @@ public function create(\SumUp\Types\CheckoutCreateRequest|array $body, ?RequestO
         ], 'POST', $path);
     }
 
+    /**
+     * Create an Apple Pay session
+     *
+     * @param string $id Unique ID of the checkout resource.
+     * @param CheckoutsCreateApplePaySessionRequest|array<string, mixed>|null $body Optional request payload
+     * @param RequestOptions|null $requestOptions Optional typed request options
+     *
+     * @return \SumUp\Services\CheckoutsCreateApplePaySessionResponse
+     * @throws \SumUp\Exception\ApiException
+     * @throws \SumUp\Exception\UnexpectedApiException
+     * @throws \SumUp\Exception\ConnectionException
+     * @throws \SumUp\Exception\SDKException
+     */
+    public function createApplePaySession(string $id, CheckoutsCreateApplePaySessionRequest|array|null $body = null, ?RequestOptions $requestOptions = null): \SumUp\Services\CheckoutsCreateApplePaySessionResponse
+    {
+        $path = sprintf('/v0.2/checkouts/%s/apple-pay-session', rawurlencode((string) $id));
+        $payload = [];
+        if ($body !== null) {
+            $payload = RequestEncoder::encode($body);
+        }
+        $headers = ['Content-Type' => 'application/json', 'User-Agent' => SdkInfo::getUserAgent()];
+        $headers = array_merge($headers, SdkInfo::getRuntimeHeaders());
+        $headers['Authorization'] = 'Bearer ' . $this->accessToken;
+
+        $response = $this->client->send('PUT', $path, $payload, $headers, $requestOptions);
+
+        return ResponseDecoder::decodeOrThrow($response, \SumUp\Services\CheckoutsCreateApplePaySessionResponse::class, [
+            '400' => ['type' => 'mixed'],
+            '404' => ['type' => 'class', 'class' => \SumUp\Types\Error::class],
+        ], 'PUT', $path);
+    }
+
     /**
      * Deactivate a checkout
      *

src/Customers/Customers.php

@@ -39,6 +39,7 @@ public function __construct(array $data = [])
  * Class Customers
  *
  * Allow your regular customers to save their information with the Customers model.
+ *
  * This will prevent re-entering payment instrument information for recurring payments on your platform.
  *
  * Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.

src/Merchants/Merchants.php

@@ -172,7 +172,6 @@ public function getPerson(string $merchantCode, string $personId, ?MerchantsGetP
 
         return ResponseDecoder::decodeOrThrow($response, \SumUp\Types\Person::class, [
             '404' => ['type' => 'class', 'class' => \SumUp\Types\Problem::class],
-            '500' => ['type' => 'class', 'class' => \SumUp\Types\Problem::class],
         ], 'GET', $path);
     }
 
@@ -213,7 +212,6 @@ public function listPersons(string $merchantCode, ?MerchantsListPersonsParams $q
 
         return ResponseDecoder::decodeOrThrow($response, \SumUp\Types\ListPersonsResponseBody::class, [
             '404' => ['type' => 'class', 'class' => \SumUp\Types\Problem::class],
-            '500' => ['type' => 'class', 'class' => \SumUp\Types\Problem::class],
         ], 'GET', $path);
     }
 }

src/Payouts/Payouts.php

@@ -33,18 +33,21 @@ class PayoutsListParams
     public string $endDate;
 
     /**
+     * Response format for the payout list.
      *
      * @var string|null
      */
     public ?string $format = null;
 
     /**
+     * Maximum number of payout records to return.
      *
      * @var int|null
      */
     public ?int $limit = null;
 
     /**
+     * Sort direction for the returned payouts.
      *
      * @var string|null
      */
@@ -74,18 +77,21 @@ class PayoutsListDeprecatedParams
     public string $endDate;
 
     /**
+     * Response format for the payout list.
      *
      * @var string|null
      */
     public ?string $format = null;
 
     /**
+     * Maximum number of payout records to return.
      *
      * @var int|null
      */
     public ?int $limit = null;
 
     /**
+     * Sort direction for the returned payouts.
      *
      * @var string|null
      */
@@ -97,6 +103,7 @@ class PayoutsListDeprecatedParams
  * Class Payouts
  *
  * The Payouts model will allow you to track funds you’ve received from SumUp.
+ *
  * You can receive a detailed payouts list with information like dates, fees, references and statuses, using the `List payouts` endpoint.
  *
  * @package SumUp\Services
@@ -132,7 +139,7 @@ public function __construct(HttpClientInterface $client, string $accessToken)
     /**
      * List payouts
      *
-     * @param string $merchantCode
+     * @param string $merchantCode Merchant code of the account whose payouts should be listed.
      * @param PayoutsListParams|null $queryParams Optional query string parameters
      * @param RequestOptions|null $requestOptions Optional typed request options
      *

src/Transactions/Transactions.php

@@ -340,8 +340,24 @@ class TransactionsListDeprecatedParams
 /**
  * Class Transactions
  *
- * Retrieve details for a specific transaction by it’s `id`
- * or any other required query parameter, or list all transactions related to the merchant account.
+ * Transactions represent completed or attempted payment operations processed for a merchant account. A transaction contains the core payment result, such as the amount, currency, payment method, creation time, and current high-level status.
+ *
+ * In addition to the main payment outcome, a transaction can contain related events that describe what happened after the original payment attempt. These events provide visibility into the financial lifecycle of the transaction, for example:
+ * - `PAYOUT`: the payment being prepared for payout or included in a payout to the merchant
+ * - `REFUND`: money returned to the payer
+ * - `CHARGE_BACK`: money reversed after the original payment
+ * - `PAYOUT_DEDUCTION`: an amount deducted from a payout to cover a refund or chargeback
+ *
+ * From an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to:
+ * - list transactions for reporting, reconciliation, and customer support workflows
+ * - retrieve a single transaction when you need the latest payment details
+ * - inspect `simple_status` for the current merchant-facing outcome of the payment
+ * - inspect `events` or `transaction_events` when you need refund, payout, or chargeback history
+ *
+ * Typical workflow:
+ * - create and process payments through the Checkouts endpoints
+ * - use the Transactions endpoints to read the resulting payment records
+ * - use the returned statuses and events to update your own order, accounting, or support systems
  *
  * @package SumUp\Services
  */
@@ -376,7 +392,7 @@ public function __construct(HttpClientInterface $client, string $accessToken)
     /**
      * Retrieve a transaction
      *
-     * @param string $merchantCode
+     * @param string $merchantCode Merchant code of the account whose transaction should be retrieved.
      * @param TransactionsGetParams|null $queryParams Optional query string parameters
      * @param RequestOptions|null $requestOptions Optional typed request options
      *
@@ -477,7 +493,7 @@ public function getDeprecated(?TransactionsGetDeprecatedParams $queryParams = nu
     /**
      * List transactions
      *
-     * @param string $merchantCode
+     * @param string $merchantCode Merchant code of the account whose transaction history should be listed.
      * @param TransactionsListParams|null $queryParams Optional query string parameters
      * @param RequestOptions|null $requestOptions Optional typed request options
      *

src/Types/Checkout.php

@@ -5,19 +5,19 @@
 namespace SumUp\Types;
 
 /**
- * Details of the payment checkout.
+ * Core checkout resource returned by the Checkouts API. A checkout is created before payment processing and then updated as payment attempts, redirects, and resulting transactions are attached to it.
  */
 class Checkout
 {
     /**
-     * Unique ID of the payment checkout specified by the client application when creating the checkout resource.
+     * Merchant-defined reference for the checkout. Use it to correlate the SumUp checkout with your own order, cart, subscription, or payment attempt in your systems.
      *
      * @var string|null
      */
     public ?string $checkoutReference = null;
 
     /**
-     * Amount of the payment.
+     * Amount to be charged to the payer, expressed in major units.
      *
      * @var float|null
      */
@@ -31,35 +31,35 @@ class Checkout
     public ?CheckoutCurrency $currency = null;
 
     /**
-     * Unique identifying code of the merchant profile.
+     * Merchant account that receives the payment.
      *
      * @var string|null
      */
     public ?string $merchantCode = null;
 
     /**
-     * Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
+     * Short merchant-defined description shown in SumUp tools and reporting. Use it to make the checkout easier to recognize in dashboards, support workflows, and reconciliation.
      *
      * @var string|null
      */
     public ?string $description = null;
 
     /**
-     * URL to which the SumUp platform sends the processing status of the payment checkout.
+     * Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.
      *
      * @var string|null
      */
     public ?string $returnUrl = null;
 
     /**
-     * Unique ID of the checkout resource.
+     * Unique SumUp identifier of the checkout resource.
      *
      * @var string|null
      */
     public ?string $id = null;
 
     /**
-     * Current status of the checkout.
+     * Current high-level state of the checkout. `PENDING` means the checkout exists but is not yet completed, `PAID` means a payment succeeded, `FAILED` means the latest processing attempt failed, and `EXPIRED` means the checkout can no longer be processed.
      *
      * @var CheckoutStatus|null
      */
@@ -73,28 +73,28 @@ class Checkout
     public ?string $date = null;
 
     /**
-     * Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
+     * Optional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time.
      *
      * @var string|null
      */
     public ?string $validUntil = null;
 
     /**
-     * Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
+     * Merchant-scoped identifier of the customer associated with the checkout. Use it when storing payment instruments or reusing saved customer context for recurring and returning-payer flows.
      *
      * @var string|null
      */
     public ?string $customerId = null;
 
     /**
-     * Created mandate
+     * Details of the mandate linked to the saved payment instrument.
      *
      * @var MandateResponse|null
      */
     public ?MandateResponse $mandate = null;
 
     /**
-     * List of transactions related to the payment.
+     * Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.
      *
      * @var mixed[]|null
      */

src/Types/CheckoutAccepted.php

@@ -5,12 +5,12 @@
 namespace SumUp\Types;
 
 /**
- * 3DS Response
+ * Response returned when checkout processing requires an additional payer action, such as a 3DS challenge or a redirect to an external payment method page.
  */
 class CheckoutAccepted
 {
     /**
-     * Required action processing 3D Secure payments.
+     * Instructions for the next action the payer or client must take.
      *
      * @var CheckoutAcceptedNextStep|null
      */

src/Types/CheckoutAcceptedNextStep.php

@@ -5,43 +5,43 @@
 namespace SumUp\Types;
 
 /**
- * Required action processing 3D Secure payments.
+ * Instructions for the next action the payer or client must take.
  */
 class CheckoutAcceptedNextStep
 {
     /**
-     * Where the end user is redirected.
+     * URL to open or submit in order to continue processing.
      *
      * @var string|null
      */
     public ?string $url = null;
 
     /**
-     * Method used to complete the redirect.
+     * HTTP method to use when following the next step.
      *
      * @var string|null
      */
     public ?string $method = null;
 
     /**
-     * Refers to a url where the end user is redirected once the payment processing completes.
+     * Merchant URL where the payer returns after the external flow finishes.
      *
      * @var string|null
      */
     public ?string $redirectUrl = null;
 
     /**
-     * Indicates allowed mechanisms for redirecting an end user. If both values are provided to ensure a redirect takes place in either.
+     * Allowed presentation mechanisms for the next step. `iframe` means the flow can be embedded, while `browser` means it can be completed through a full-page redirect.
      *
      * @var string[]|null
      */
     public ?array $mechanism = null;
 
     /**
-     * Contains parameters essential for form redirection. Number of object keys and their content can vary.
+     * Parameters required to complete the next step. The exact keys depend on the payment provider and flow type.
      *
-     * @var CheckoutAcceptedNextStepPayload|null
+     * @var array<string, mixed>|null
      */
-    public ?CheckoutAcceptedNextStepPayload $payload = null;
+    public ?array $payload = null;
 
 }