PhonePe Auto-Debit API请求结构错误排查及正确配置咨询

错误响应 #

{
"status": "error",
"message": "Please check the inputs you have provided. [message = Incorrect Request.]"
}

提交的请求Payload #

{
  "merchantId": "MID12345",
  "merchantUserId": "U123456789",
  "subscriptionId": "OMS2006110139450123456789",
  "transactionId": "TX1234567890",
  "autoDebit": true,
  "amount": 39900
}

问题诉求 #

集成该API时持续收到上述错误，已对照官方文档确认格式仍未解决，需明确：

• 请求Payload是否缺少必填字段？
• X-VERIFY签名是否有误？
• 如何正确构造请求避免该错误？

已完成的检查项 #

• 确保transactionId每个请求唯一
• 验证金额为paisa格式（如₹399.00=39900）
• 在Postman中使用硬编码值测试
• 检查subscriptionId格式正确性
• 按文档生成X-VERIFY哈希
• 记录请求Payload确认结构正确

预期结果 #

获取包含交易详情的成功API响应

最小复现代码 #

$apiKey = 'your_salt_key';
$baseUrl = 'https://mercury-t2.phonepe.com';
$subscriptionId = 'SUB123456';
$transactionId = 'TX' . strtoupper(bin2hex(random_bytes(8))); // 生成唯一交易ID
$amount = 10000; // 金额（单位：paisa，即₹100）
$callurl = "https://yourdomain.com/api/phonepe/callback";

// 请求Payload
$authPayload_1 = [
  'merchantId' => 'your_merchant_id',
  'merchantUserId' => 'your_merchant_id',
  'subscriptionId' => $subscriptionId,  
  'transactionId' => $transactionId,
  'autoDebit' => true,
  'amount' => $amount,
];
$base64Payload = base64_encode(json_encode($authPayload_1));
$payloadHash_1 = $base64Payload . '/v3/recurring/debit/init' . $apiKey;
$checksum_a = hash('sha256', $payloadHash_1);
$xVerifyy = $checksum_a . '###' . 'your_salt_index';

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => $baseUrl . '/v3/recurring/debit/init',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode(['request' => $base64Payload]),
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-VERIFY: ' . $xVerifyy,
    'X-CALLBACK-URL: '.$callurl
  ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$responseData = json_decode($response, true);
var_dump($responseData);

问题排查与修复建议 #

1. Payload字段赋值错误
   复现代码中merchantUserId被错误赋值为商户ID，该字段应为用户唯一标识（如平台内用户ID），而非商户ID，这是触发错误的核心原因之一。

2. 签名生成优化

   • json_encode时需添加JSON_UNESCAPED_SLASHES参数，避免base64编码后出现不必要的转义字符，确保签名计算准确：

     $base64Payload = base64_encode(json_encode($authPayload_1, JSON_UNESCAPED_SLASHES));
     

   • 确认salt_key和salt_index与PhonePe商户后台配置完全一致，签名拼接顺序必须严格遵循：base64Payload + API路径 + salt_key，再做SHA256哈希，最后拼接###salt_index。

3. 补充必填字段
   部分环境下需显式传递currency字段，建议在Payload中添加：

   "currency": "INR"
   

4. 环境与回调URL验证

   • 确认测试环境URL正确，回调URL需为公网可访问的HTTPS地址，且未被防火墙拦截；
   • 检查请求头Content-Type严格为application/json，Postman测试时需移除无关请求头干扰。

内容的提问来源于stack exchange，提问作者Eagleminds Technologies