From d4db68f2e7896f6af828599ea697b5b298034817 Mon Sep 17 00:00:00 2001
From: Anatoliy Poloz <t0ly.od@yandex.ru>
Date: Tue, 7 Apr 2026 18:47:53 +0300
Subject: [PATCH] refactor(error): handling

---
 src/Traits/HasAlfaErrorHandling.php | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/Traits/HasAlfaErrorHandling.php b/src/Traits/HasAlfaErrorHandling.php
index 12f8157..bc59e3b 100644
--- a/src/Traits/HasAlfaErrorHandling.php
+++ b/src/Traits/HasAlfaErrorHandling.php
@@ -43,7 +43,8 @@ trait HasAlfaErrorHandling
         if (str_contains($contentType, 'application/json')) {
             $data = $response->json();
             $errorCode = $data['error'] ?? $data['ErrorCode'] ?? 'HTTP_' . $response->status();
-            $errorDescription = $data['error_description'] ?? $data['message'] ?? 'Request failed';
+            $rawDescription = $data['error_description'] ?? $data['message'] ?? 'Request failed';
+            $errorDescription = $this->decodeBankMessage($rawDescription);
         } else {
             $errorCode = 'HTTP_' . $response->status();
             $errorDescription = 'Request failed with status ' . $response->status();
@@ -55,4 +56,15 @@ trait HasAlfaErrorHandling
             "({$requestId}) {$errorDescription}"
         );
     }
+
+    private function decodeBankMessage(string $message): string
+    {
+        $decoded = preg_replace_callback(
+            '/%u([0-9A-Fa-f]{4})/',
+            fn ($m) => mb_convert_encoding(pack('H*', $m[1]), 'UTF-8', 'UCS-2BE'),
+            $message
+        );
+
+        return urldecode($decoded);
+    }
 }