PAGGUE平台PIX充值生成QR码报错：Illegal string offset 'hash'

错误本质 #

Illegal string offset 'hash' 这个错误明确说明：你试图通过数组键'hash'从字符串中取值，但字符串不支持这种数组式的键访问——也就是说变量$response并不是你预期的包含hash字段的关联数组，而是一个字符串（比如未解析的JSON、API错误提示文本等）。

排查与解决步骤 #

• 第一步：确认$response的真实内容和类型
  在出错代码前添加日志或调试代码，明确$response到底是什么：

  // 生产环境用日志记录，避免影响用户
  Log::info('PAGGUE API Response Details:', [
      'response_content' => $response,
      'response_type' => gettype($response)
  ]);
  
  // 测试环境可以直接打印查看
  var_dump($response);
  exit;
  

  执行后查看日志或输出，就能知道$response是未解析的JSON字符串，还是API返回的错误信息。

• 如果是未解析的JSON字符串
  先将JSON解码为关联数组，再安全地获取hash字段：

  // 解码JSON为关联数组
  $decodedResponse = json_decode($response, true);
  
  // 先判断hash字段是否存在，避免再次报错
  if (isset($decodedResponse['hash'])) {
      $payment->secret = $decodedResponse['hash'];
  } else {
      // 记录错误并处理异常情况
      Log::error('PAGGUE API Response missing required "hash" field:', ['response' => $decodedResponse]);
      // 这里添加业务逻辑，比如终止充值流程、返回错误提示给用户
  }
  

• 如果API返回的是错误响应
  先检查API请求的HTTP状态码，确认调用是否成功：

  $client = new \GuzzleHttp\Client();
  try {
      $apiResponse = $client->post('你的PAGGUE API接口地址', [
          // 这里填充请求参数，比如headers、form_params等
      ]);
  
      // 仅当请求成功时处理响应
      if ($apiResponse->getStatusCode() === 200) {
          $response = json_decode($apiResponse->getBody(), true);
          if (isset($response['hash'])) {
              $payment->secret = $response['hash'];
          } else {
              Log::error('PAGGUE API Response missing "hash" field:', ['response' => $response]);
          }
      } else {
          // 记录错误状态码和响应内容
          $errorContent = $apiResponse->getBody()->getContents();
          Log::error('PAGGUE API Request Failed:', [
              'status_code' => $apiResponse->getStatusCode(),
              'error_content' => $errorContent
          ]);
          // 返回充值失败提示给用户
      }
  } catch (\GuzzleHttp\Exception\RequestException $e) {
      // 捕获请求异常，比如网络错误、超时等
      Log::error('PAGGUE API Request Exception:', ['message' => $e->getMessage()]);
  }
  

关于忽略hash后QR码无效的说明 #

PIX支付的QR码生成依赖hash（即你代码中的$payment->secret）作为支付请求的唯一标识，PAGGUE平台需要通过这个字段关联用户的充值请求和实际支付行为，所以缺少这个字段必然会导致QR码无效，必须正确获取到hash才能生成有效的支付二维码。

内容的提问来源于stack exchange，提问作者Edir Inacio