feat(php-sdk): replace magic request option arrays with typed RequestOptions

Introduce SumUp\HttpClient\RequestOptions and use it across the SDK surface.\n\n- Update HttpClientInterface and built-in clients to accept typed request options\n- Update codegen to emit RequestOptions in generated service method signatures/docs\n- Regenerate service files\n- Update examples and README with typed request options usage

Author: matoous

README.md

@@ -37,12 +37,13 @@ try {
     // SDK automatically uses SUMUP_API_KEY environment variable
     $sumup = new \SumUp\SumUp();
 
-    $checkout = $sumup->checkouts()->create([
-        'amount' => 10.00,
-        'currency' => 'EUR',
-        'checkout_reference' => 'your-checkout-ref',
-        'merchant_code' => 'YOUR-MERCHANT-CODE',
-    ]);
+    $request = new \SumUp\Types\CheckoutCreateRequest();
+    $request->amount = 10.00;
+    $request->currency = \SumUp\Types\CheckoutCreateRequestCurrency::EUR;
+    $request->checkoutReference = 'your-checkout-ref';
+    $request->merchantCode = 'YOUR-MERCHANT-CODE';
+
+    $checkout = $sumup->checkouts()->create($request);
 
     $checkoutId = $checkout->id;
     // Pass the $checkoutId to the front-end to be processed
@@ -53,13 +54,16 @@ try {
 } catch (\SumUp\Exception\UnexpectedApiException $e) {
     echo 'Unexpected API error (status ' . $e->getStatusCode() . '): ' . $e->getMessage();
     // Body did not match an OpenAPI-described error shape.
-    var_dump($e->getResponseBody());
+    // Use the normalized envelope for stable logging/handling.
+    var_dump($e->getErrorEnvelope()->toArray());
 } catch (\SumUp\Exception\SDKException $e) {
     echo 'SumUp SDK error (status ' . $e->getStatusCode() . '): ' . $e->getMessage();
     // Covers connection/configuration and other non-API failures.
 }
 ```
 
+For convenience, service methods still accept associative arrays as request payloads, but DTO objects from `\SumUp\Types\...` are the recommended and typed approach.
+
 ### Providing API Key Programmatically
 
 If you prefer to provide the API key directly in your code instead of using the environment variable:
@@ -118,6 +122,21 @@ $sumup = new \SumUp\SumUp([
 ]);
 ```
 
+### Request Options
+
+Service methods accept typed request options via `\SumUp\HttpClient\RequestOptions`:
+
+```php
+$options = new \SumUp\HttpClient\RequestOptions(
+    timeout: 30,
+    connectTimeout: 10,
+    retries: 2,
+    retryBackoffMs: 200
+);
+
+$checkout = $sumup->checkouts()->get('checkout-id', $options);
+```
+
 ## API Reference
 
 For a full list of available services and methods, explore the service files under `src/*/*.php` (for example `src/Checkouts/Checkouts.php`) or check the inline documentation in the code.

codegen/pkg/generator/services.go

@@ -20,6 +20,7 @@ func (g *Generator) buildServiceBlock(tagKey string, operations []*operation) st
 	var buf strings.Builder
 	buf.WriteString("namespace SumUp\\Services;\n\n")
 	buf.WriteString("use SumUp\\HttpClient\\HttpClientInterface;\n")
+	buf.WriteString("use SumUp\\HttpClient\\RequestOptions;\n")
 	if serviceHasRequestBody(operations) {
 		buf.WriteString("use SumUp\\RequestEncoder;\n")
 	}
@@ -196,7 +197,7 @@ func (g *Generator) renderServiceMethod(serviceClass string, op *operation) stri
 	if op.HasBody {
 		fmt.Fprintf(&buf, "     * @param %s $body %s request payload\n", renderBodyDocType(op), renderBodyDocQualifier(op))
 	}
-	buf.WriteString("     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)\n")
+	buf.WriteString("     * @param RequestOptions|null $requestOptions Optional typed request options\n")
 
 	buf.WriteString("     *\n")
 	fmt.Fprintf(&buf, "     * @return %s\n", renderOperationReturnDoc(op))
@@ -222,7 +223,7 @@ func (g *Generator) renderServiceMethod(serviceClass string, op *operation) stri
 	if op.HasBody {
 		args = append(args, renderBodyArgument(op))
 	}
-	args = append(args, "?array $requestOptions = null")
+	args = append(args, "?RequestOptions $requestOptions = null")
 
 	buf.WriteString("    public function ")
 	buf.WriteString(methodName)

examples/custom-http-client.php

@@ -42,8 +42,13 @@ public function __construct(\SumUp\HttpClient\HttpClientInterface $wrappedClient
         $this->wrappedClient = $wrappedClient;
     }
 
-    public function send(string $method, string $url, array $body, array $headers, ?array $options = null): \SumUp\HttpClient\Response
-    {
+    public function send(
+        string $method,
+        string $url,
+        array $body,
+        array $headers,
+        ?\SumUp\HttpClient\RequestOptions $options = null
+    ): \SumUp\HttpClient\Response {
         // Log the request
         echo "[HTTP Request] {$method} {$url}\n";
         if (!empty($body)) {
@@ -86,6 +91,11 @@ public function send(string $method, string $url, array $body, array $headers, ?
     $merchant = $sumup->merchants()->get($merchantCode);
     echo "\nMerchant retrieved successfully!\n";
     echo "Merchant code: " . $merchant->merchantCode . "\n";
+} catch (\SumUp\Exception\ApiException $e) {
+    echo "API error: " . $e->getMessage() . "\n";
+} catch (\SumUp\Exception\UnexpectedApiException $e) {
+    echo "Unexpected API error: " . $e->getMessage() . "\n";
+    echo "Envelope: " . json_encode($e->getErrorEnvelope()->toArray()) . "\n";
 } catch (\SumUp\Exception\SDKException $e) {
     echo "Error: " . $e->getMessage() . "\n";
 }

examples/guzzle-http-client.php

@@ -38,6 +38,11 @@
     $merchant = $sumup->merchants()->get($merchantCode);
     echo "\nMerchant retrieved successfully!\n";
     echo "Merchant code: " . $merchant->merchantCode . "\n";
+} catch (\SumUp\Exception\ApiException $e) {
+    echo "API error: " . $e->getMessage() . "\n";
+} catch (\SumUp\Exception\UnexpectedApiException $e) {
+    echo "Unexpected API error: " . $e->getMessage() . "\n";
+    echo "Envelope: " . json_encode($e->getErrorEnvelope()->toArray()) . "\n";
 } catch (\SumUp\Exception\SDKException $e) {
     echo "Error: " . $e->getMessage() . "\n";
 }

examples/oauth2/README.md

@@ -86,12 +86,13 @@ $sumup = new \SumUp\SumUp();
 $sumup->setDefaultAccessToken($accessToken);
 
 // Use the SDK normally
-$checkout = $sumup->checkouts()->create([
-    'amount' => 10.00,
-    'currency' => 'EUR',
-    'checkout_reference' => 'order-123',
-    'merchant_code' => $merchantCode,
-]);
+$request = new \SumUp\Types\CheckoutCreateRequest();
+$request->amount = 10.00;
+$request->currency = \SumUp\Types\CheckoutCreateRequestCurrency::EUR;
+$request->checkoutReference = 'order-123';
+$request->merchantCode = $merchantCode;
+
+$checkout = $sumup->checkouts()->create($request);
 ```
 
 ## Token Storage

examples/simple.php

@@ -33,7 +33,17 @@
 // $sumup->setDefaultAccessToken('your-token-here');
 
 // Use services with the default token
-$merchant = $sumup->merchants()->get($merchantCode);
-print_r($merchant);
+try {
+    $requestOptions = new \SumUp\HttpClient\RequestOptions(timeout: 30, connectTimeout: 10);
+    $merchant = $sumup->merchants()->get($merchantCode, null, $requestOptions);
+    print_r($merchant);
+} catch (\SumUp\Exception\ApiException $e) {
+    fwrite(STDERR, "API error: " . $e->getMessage() . "\n");
+} catch (\SumUp\Exception\UnexpectedApiException $e) {
+    fwrite(STDERR, "Unexpected API error: " . $e->getMessage() . "\n");
+    fwrite(STDERR, json_encode($e->getErrorEnvelope()->toArray(), JSON_PRETTY_PRINT) . "\n");
+} catch (\SumUp\Exception\SDKException $e) {
+    fwrite(STDERR, "SDK error: " . $e->getMessage() . "\n");
+}
 
 // Override the default token by creating a new client instance instead.

src/Checkouts/Checkouts.php

@@ -7,6 +7,7 @@
 namespace SumUp\Services;
 
 use SumUp\HttpClient\HttpClientInterface;
+use SumUp\HttpClient\RequestOptions;
 use SumUp\RequestEncoder;
 use SumUp\ResponseDecoder;
 use SumUp\SdkInfo;
@@ -97,15 +98,15 @@ public function __construct(HttpClientInterface $client, string $accessToken)
      * Create a checkout
      *
      * @param \SumUp\Types\CheckoutCreateRequest|array<string, mixed> $body Required request payload
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\Checkout
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function create(\SumUp\Types\CheckoutCreateRequest|array $body, ?array $requestOptions = null): \SumUp\Types\Checkout
+    public function create(\SumUp\Types\CheckoutCreateRequest|array $body, ?RequestOptions $requestOptions = null): \SumUp\Types\Checkout
     {
         $path = '/v0.1/checkouts';
         $payload = [];
@@ -130,15 +131,15 @@ public function create(\SumUp\Types\CheckoutCreateRequest|array $body, ?array $r
      * Deactivate a checkout
      *
      * @param string $id Unique ID of the checkout resource.
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\Checkout
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function deactivate(string $id, ?array $requestOptions = null): \SumUp\Types\Checkout
+    public function deactivate(string $id, ?RequestOptions $requestOptions = null): \SumUp\Types\Checkout
     {
         $path = sprintf('/v0.1/checkouts/%s', rawurlencode((string) $id));
         $payload = [];
@@ -159,15 +160,15 @@ public function deactivate(string $id, ?array $requestOptions = null): \SumUp\Ty
      * Retrieve a checkout
      *
      * @param string $id Unique ID of the checkout resource.
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\CheckoutSuccess
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function get(string $id, ?array $requestOptions = null): \SumUp\Types\CheckoutSuccess
+    public function get(string $id, ?RequestOptions $requestOptions = null): \SumUp\Types\CheckoutSuccess
     {
         $path = sprintf('/v0.1/checkouts/%s', rawurlencode((string) $id));
         $payload = [];
@@ -187,15 +188,15 @@ public function get(string $id, ?array $requestOptions = null): \SumUp\Types\Che
      * List checkouts
      *
      * @param CheckoutsListParams|null $queryParams Optional query string parameters
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\CheckoutSuccess[]
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function list(?CheckoutsListParams $queryParams = null, ?array $requestOptions = null): array
+    public function list(?CheckoutsListParams $queryParams = null, ?RequestOptions $requestOptions = null): array
     {
         $path = '/v0.1/checkouts';
         if ($queryParams !== null) {
@@ -229,15 +230,15 @@ public function list(?CheckoutsListParams $queryParams = null, ?array $requestOp
      *
      * @param string $merchantCode The SumUp merchant code.
      * @param CheckoutsListAvailablePaymentMethodsParams|null $queryParams Optional query string parameters
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Services\CheckoutsListAvailablePaymentMethodsResponse
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function listAvailablePaymentMethods(string $merchantCode, ?CheckoutsListAvailablePaymentMethodsParams $queryParams = null, ?array $requestOptions = null): \SumUp\Services\CheckoutsListAvailablePaymentMethodsResponse
+    public function listAvailablePaymentMethods(string $merchantCode, ?CheckoutsListAvailablePaymentMethodsParams $queryParams = null, ?RequestOptions $requestOptions = null): \SumUp\Services\CheckoutsListAvailablePaymentMethodsResponse
     {
         $path = sprintf('/v0.1/merchants/%s/payment-methods', rawurlencode((string) $merchantCode));
         if ($queryParams !== null) {
@@ -273,15 +274,15 @@ public function listAvailablePaymentMethods(string $merchantCode, ?CheckoutsList
      *
      * @param string $id Unique ID of the checkout resource.
      * @param \SumUp\Types\ProcessCheckout|array<string, mixed> $body Required request payload
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\CheckoutSuccess|\SumUp\Types\CheckoutAccepted
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function process(string $id, \SumUp\Types\ProcessCheckout|array $body, ?array $requestOptions = null): \SumUp\Types\CheckoutSuccess|\SumUp\Types\CheckoutAccepted
+    public function process(string $id, \SumUp\Types\ProcessCheckout|array $body, ?RequestOptions $requestOptions = null): \SumUp\Types\CheckoutSuccess|\SumUp\Types\CheckoutAccepted
     {
         $path = sprintf('/v0.1/checkouts/%s', rawurlencode((string) $id));
         $payload = [];

src/Customers/Customers.php

@@ -7,6 +7,7 @@
 namespace SumUp\Services;
 
 use SumUp\HttpClient\HttpClientInterface;
+use SumUp\HttpClient\RequestOptions;
 use SumUp\RequestEncoder;
 use SumUp\ResponseDecoder;
 use SumUp\SdkInfo;
@@ -59,15 +60,15 @@ public function __construct(HttpClientInterface $client, string $accessToken)
      * Create a customer
      *
      * @param \SumUp\Types\Customer|array<string, mixed> $body Required request payload
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\Customer
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function create(\SumUp\Types\Customer|array $body, ?array $requestOptions = null): \SumUp\Types\Customer
+    public function create(\SumUp\Types\Customer|array $body, ?RequestOptions $requestOptions = null): \SumUp\Types\Customer
     {
         $path = '/v0.1/customers';
         $payload = [];
@@ -92,15 +93,15 @@ public function create(\SumUp\Types\Customer|array $body, ?array $requestOptions
      *
      * @param string $customerId Unique ID of the saved customer resource.
      * @param string $token Unique token identifying the card saved as a payment instrument resource.
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return null
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function deactivatePaymentInstrument(string $customerId, string $token, ?array $requestOptions = null): null
+    public function deactivatePaymentInstrument(string $customerId, string $token, ?RequestOptions $requestOptions = null): null
     {
         $path = sprintf('/v0.1/customers/%s/payment-instruments/%s', rawurlencode((string) $customerId), rawurlencode((string) $token));
         $payload = [];
@@ -123,15 +124,15 @@ public function deactivatePaymentInstrument(string $customerId, string $token, ?
      * Retrieve a customer
      *
      * @param string $customerId Unique ID of the saved customer resource.
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\Customer
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function get(string $customerId, ?array $requestOptions = null): \SumUp\Types\Customer
+    public function get(string $customerId, ?RequestOptions $requestOptions = null): \SumUp\Types\Customer
     {
         $path = sprintf('/v0.1/customers/%s', rawurlencode((string) $customerId));
         $payload = [];
@@ -152,15 +153,15 @@ public function get(string $customerId, ?array $requestOptions = null): \SumUp\T
      * List payment instruments
      *
      * @param string $customerId Unique ID of the saved customer resource.
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\PaymentInstrumentResponse[]
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function listPaymentInstruments(string $customerId, ?array $requestOptions = null): array
+    public function listPaymentInstruments(string $customerId, ?RequestOptions $requestOptions = null): array
     {
         $path = sprintf('/v0.1/customers/%s/payment-instruments', rawurlencode((string) $customerId));
         $payload = [];
@@ -184,15 +185,15 @@ public function listPaymentInstruments(string $customerId, ?array $requestOption
      *
      * @param string $customerId Unique ID of the saved customer resource.
      * @param CustomersUpdateRequest|array<string, mixed> $body Required request payload
-     * @param array<string, mixed>|null $requestOptions Optional request options (timeout, connect_timeout, retries, retry_backoff_ms)
+     * @param RequestOptions|null $requestOptions Optional typed request options
      *
      * @return \SumUp\Types\Customer
      * @throws \SumUp\Exception\ApiException
      * @throws \SumUp\Exception\UnexpectedApiException
      * @throws \SumUp\Exception\ConnectionException
      * @throws \SumUp\Exception\SDKException
      */
-    public function update(string $customerId, CustomersUpdateRequest|array $body, ?array $requestOptions = null): \SumUp\Types\Customer
+    public function update(string $customerId, CustomersUpdateRequest|array $body, ?RequestOptions $requestOptions = null): \SumUp\Types\Customer
     {
         $path = sprintf('/v0.1/customers/%s', rawurlencode((string) $customerId));
         $payload = [];