Unit tests + connected codebase fixes

src/Exceptions/InvalidRequestException.php

@@ -4,17 +4,21 @@
 
 namespace Yiisoft\Payments\Exceptions;
 
 class InvalidRequestException extends PaymentException
 {
+    /**
+     * @param array<string,mixed>|null $details
+     */
     public function __construct(
         string $message = 'Invalid request',
         ?string $errorCode = null,
         ?string $errorType = null,
         ?string $declineCode = null,
         ?string $param = null,
+        ?array $details = null,
         int $code = 400,
         ?\Throwable $previous = null
     ) {
-        parent::__construct($message, $errorCode, $errorType, $declineCode, $param, $code, $previous);
+        parent::__construct($message, $errorCode, $errorType, $declineCode, $param, $details, $code, $previous);
     }
 }

src/Exceptions/PaymentException.php

@@ -6,12 +6,16 @@
 
 class PaymentException extends \RuntimeException
 {
+    /**
+     * @param array<string,mixed>|null $details
+     */
     public function __construct(
         string $message = '',
         public readonly ?string $errorCode = null,
         public readonly ?string $errorType = null,
         public readonly ?string $declineCode = null,
         public readonly ?string $param = null,
+        public readonly ?array $details = null,
         int $code = 0,
         ?\Throwable $previous = null
     ) {

src/Gateways/AbstractGateway.php

@@ -17,7 +17,7 @@
 
 abstract class AbstractGateway implements PaymentGatewayInterface
 {
     protected const API_VERSION = '1.0.0';
 
     public function __construct(
         protected ClientInterface $httpClient,
@@ -56,7 +56,7 @@
             ->withHeader('User-Agent', 'PaymentGateway/' . self::API_VERSION);
     }
 
     protected function sendRequest($request): array
     {
         try {
             $response = $this->httpClient->sendRequest($request);
@@ -79,33 +79,93 @@
 
     protected function handleErrorResponse(array $response, int $statusCode): void
     {
-        $error = $response['error'] ?? [];
-        $message = $error['message'] ?? 'An error occurred with the payment gateway';
-        $code = $error['code'] ?? null;
-        $type = $error['type'] ?? null;
-        $declineCode = $error['decline_code'] ?? null;
-        $param = $error['param'] ?? null;
+        $error = isset($response['error']) && is_array($response['error'])
+            ? $response['error']
+            : $response;
+
+        $message = $this->extractErrorMessage($error)
+            ?? $this->extractErrorMessage($response)
+            ?? 'An error occurred with the payment gateway';
+
+        $code = $this->extractErrorField($error, ['code', 'Code', 'error_code', 'ErrorCode', 'ResultCode']);
+        $type = $this->extractErrorField($error, ['type', 'Type', 'error_type', 'ErrorType']);
+        $declineCode = $this->extractErrorField($error, ['decline_code', 'DeclineCode']);
+        $param = $this->extractErrorField($error, ['param', 'Param', 'parameter', 'Parameter']);
+        $details = [
+            'response' => $response,
+        ];
 
         switch ($statusCode) {
             case 400:
-                throw new \Yiisoft\Payments\Exceptions\InvalidRequestException(
+                throw new InvalidRequestException(
                     $message,
                     $code,
                     $type,
                     $declineCode,
                     $param,
+                    $details,
                     $statusCode
                 );
-            // Add more specific exceptions as needed
             default:
-                throw new \Yiisoft\Payments\Exceptions\PaymentException(
+                throw new PaymentException(
                     $message,
                     $code,
                     $type,
                     $declineCode,
                     $param,
+                    $details,
                     $statusCode
                 );
         }
     }
+
+    private function extractErrorMessage(array $payload): ?string
+    {
+        $message = $this->extractErrorField(
+            $payload,
+            ['message', 'Message', 'description', 'Description', 'detail', 'Detail', 'title', 'Title', 'error_description', 'error_message', 'Error']
+        );
+
+        if ($message !== null && $message !== '') {
+            return $message;
+        }
+
+        $errors = $payload['errors'] ?? $payload['Errors'] ?? null;
+        if (is_array($errors) && $errors !== []) {
+            $first = reset($errors);
+            if (is_array($first)) {
+                return $this->extractErrorMessage($first);
+            }
+
+            if (is_scalar($first)) {
+                return (string) $first;
+            }
+        }
+
+        $error = $payload['error'] ?? null;
+        if (is_scalar($error) && $error !== '') {
+            return (string) $error;
+        }
+
+        return null;
+    }
+
+    /**
+     * @param list<string> $keys
+     */
+    private function extractErrorField(array $payload, array $keys): ?string
+    {
+        foreach ($keys as $key) {
+            if (!array_key_exists($key, $payload)) {
+                continue;
+            }
+
+            $value = $payload[$key];
+            if (is_scalar($value) && $value !== '') {
+                return (string) $value;
+            }
+        }
+
+        return null;
+    }
 }

src/Gateways/PayPalGateway.php

@@ -52,7 +52,7 @@
 
     protected function getBaseUri(): string
     {
         return $this->endpoints->getBaseUri($this->sandbox);
     }
 
     /**
@@ -60,6 +60,9 @@
      *
      * This method returns the given model with an assigned ID if it doesn't have one. No API call is made.
      * The returned ID is stable only within the calling application (store it yourself if needed).
+     * 
+     * @sandbox-support not_implemented
+     * @sandbox-reason PayPal public API does not expose a standalone customer resource or customer CRUD endpoints compatible with this interface. This operation cannot be implemented against the public PayPal API.
      */
     public function createCustomer(Customer $customer): Customer
     {
@@ -83,6 +86,10 @@
      *
      * This method returns a placeholder customer with the provided ID.
      */
+    /**
+     * @sandbox-support not_implemented
+     * @sandbox-reason PayPal public API does not expose a standalone customer resource or customer CRUD endpoints compatible with this interface. This operation cannot be implemented against the public PayPal API.
+     */
     public function retrieveCustomer(string $customerId): Customer
     {
         return new Customer(id: $customerId);
@@ -93,6 +100,10 @@
      *
      * This method returns the input customer unchanged.
      */
+    /**
+     * @sandbox-support not_implemented
+     * @sandbox-reason PayPal public API does not expose a standalone customer resource or customer update endpoint compatible with this interface. This operation cannot be implemented against the public PayPal API.
+     */
     public function updateCustomer(Customer $customer): Customer
     {
         return $customer;
@@ -102,6 +113,9 @@
      * PayPal does not expose a generic "Customer" resource compatible with this library's interface.
      *
      * This method is a no-op.
+     * 
+     * @sandbox-support not_implemented
+     * @sandbox-reason PayPal public API does not expose a standalone customer resource or customer deletion endpoint compatible with this interface. This operation cannot be implemented against the public PayPal API.
      */
     public function deleteCustomer(string $customerId): void
     {
@@ -119,11 +133,13 @@
      * Optional metadata keys used by this gateway:
      * - return_url: URL where PayPal will redirect the payer after approval (web flow)
      * - cancel_url: URL where PayPal will redirect the payer if they cancel (web flow)
+     * 
+     * @sandbox-support implemented
      */
     public function createPaymentIntent(PaymentIntent $paymentIntent): PaymentIntent
     {
         $currency = strtoupper($paymentIntent->currency);
         $amount = self::formatAmount($paymentIntent->amount);
 
         $data = [
             'intent' => $paymentIntent->captureMethod ? 'AUTHORIZE' : 'CAPTURE',
@@ -144,7 +160,7 @@
             $data['purchase_units'][0]['description'] = $paymentIntent->description;
         }
 
         if (!empty($paymentIntent->metadata)) {
             // A convenient way to pass application-specific identifiers into PayPal.
             if (isset($paymentIntent->metadata['order_id'])) {
                 $data['purchase_units'][0]['custom_id'] = (string) $paymentIntent->metadata['order_id'];
@@ -170,8 +186,10 @@
 
     /**
      * Retrieves PayPal Order data.
+     * 
+     * @sandbox-support implemented
      */
     public function retrievePaymentIntent(string $paymentIntentId): PaymentIntent
     {
         $order = $this->sendRequest(
             $this->createRequest('GET', "/v2/checkout/orders/{$paymentIntentId}")
@@ -185,8 +203,11 @@
      *
      * For PayPal web flows, payer approval happens outside of the API (via approval link).
      * This method simply re-fetches the current order state.
+     * 
+     * @sandbox-support partial
+     * @sandbox-reason PayPal order approval is performed by the payer on PayPal-hosted pages. The public API does not expose a separate generic confirm endpoint compatible with this interface.
      */
     public function confirmPaymentIntent(string $paymentIntentId, array $params = []): PaymentIntent
     {
         return $this->retrievePaymentIntent($paymentIntentId);
     }
@@ -199,8 +220,10 @@
      *
      * If you already have an authorization ID and want to capture it explicitly, pass it as:
      *   $this->capturePaymentIntent($orderId, ['authorization_id' => '...'])
+     * 
+     * @sandbox-support implemented
      */
         public function capturePaymentIntent(string $paymentIntentId, array $params = []): PaymentIntent
     {
         // Optional: confirm payment source (used for advanced card payments flows).
         //
@@ -219,6 +242,7 @@
                     'paypal',
                     null,
                     'payment_source',
+                    null,
                     400
                 );
             }
@@ -288,7 +312,10 @@
         ]);
     }
 
-public function cancelPaymentIntent(string $paymentIntentId, array $params = []): PaymentIntent
+    /**
+     * @sandbox-support implemented
+     */
+    public function cancelPaymentIntent(string $paymentIntentId, array $params = []): PaymentIntent
     {
         try {
             $order = $this->sendRequest(
@@ -306,6 +333,9 @@
      * PayPal does not expose a generic "PaymentMethod" resource compatible with this library's interface.
      *
      * This method returns the given model with an assigned ID if it doesn't have one. No API call is made.
+     * 
+     * @sandbox-support not_implemented
+     * @sandbox-reason PayPal public API does not expose a standalone generic payment-method resource compatible with this interface. This operation cannot be implemented against the public PayPal API.
      */
     public function createPaymentMethod(PaymentMethod $paymentMethod): PaymentMethod
     {
@@ -357,6 +387,9 @@
      * PayPal does not expose a generic "PaymentMethod" attachment API compatible with this library's interface.
      *
      * This method returns the payment method unchanged.
+     * 
+     * @sandbox-support not_implemented
+     * @sandbox-reason PayPal public API does not expose a generic payment-method attachment endpoint compatible with this interface. This operation cannot be implemented against the public PayPal API.
      */
     public function attachPaymentMethod(string $paymentMethodId, string $customerId): PaymentMethod
     {
@@ -370,6 +403,8 @@
      * To use this method you must pass a capture ID either:
      * - as $paymentIntentId directly; OR
      * - as ['capture_id' => '...'] in $params
+     * 
+     * @sandbox-support implemented
      */
     public function createRefund(string $paymentIntentId, array $params = []): array
     {
@@ -440,6 +475,7 @@
             'paypal',
             null,
             $param,
+            null,
             $statusCode
         );
     }
@@ -470,6 +506,7 @@
                 'paypal',
                 null,
                 null,
+                null,
                 $response->getStatusCode()
             );
         }