PAYATHON 2026

ICICI IMPS payment API 在 Postman 中无法调用

支付小周

结论

问题出在 Header 名称，不是请求参数。

API key

这个名称包含空格，不符合 HTTP Header 字段名的格式要求。Postman 会在发送请求前拒绝它，并提示：

API key is not a valid HTTP header field name

请将它改成 ICICI API 文档规定的 Header 名称，例如：

API-Key

或：

apikey

具体拼写要以 ICICI Developer Portal 中对应接口的 API 文档或示例请求为准。页面上的 API key 可能只是标签，不能直接当作 Header 名称。

为什么 Portal 中可以运行

Developer Portal 显示的 API key 可能只是输入框标签。门户发送请求时，通常会把输入值放入实际的 HTTP Header，例如：

API-Key: xxxxxxx

Postman 则会直接使用你填写的 Header 名称。如果填写：

API key: xxxxxxx

名称中的空格会违反 HTTP Header 字段名的格式要求，请求还没到达 ICICI 服务器就会失败。

所以，相同参数在 Portal 中可以使用，在 Postman 中却报错，是因为两个界面实际生成的 Header 不一定相同。

Postman 中的正确配置

在 Postman 的 Headers 页面中，每个 Header 单独占一行。不要在 Key 或 Value 中加入冒号、逗号或多余空格。

如果接口文档规定 API Key 的字段名是 API-Key，可按下面的方式填写：

KeyValue
Content-Typeapplication/json
API-Keyxxxxxxx
Priority000000

下面的写法不正确：

KeyValue
API keyxxxxxxx,
Priority:000000留空

填写时注意：

  • Header 名称和 Header 值要分开填写。
  • Key 中不能包含冒号。
  • API Key 值末尾不能带逗号。
  • Header 名称前后不能有空格。
  • 000000 应保留为字符串，避免被工具转换成数字 0。

请求体配置

在 Postman 中选择：

Body → raw → JSON

然后填写：

{
  "localTxnDtTime": "20200121160503",
  "beneAccNo": "057001510618",
  "beneIFSC": "ICIC0000570",
  "amount": "1",
  "tranRefNo": "17df6a44e57f436492f66f6",
  "paymentRef": "FTTransferP2A",
  "senderName": "APIGATEWAY",
  "mobile": "7588215033",
  "retailerCode": "rcode",
  "passCode": "d1118d6f9fe94696b4b1e1a0980bb396",
  "bcID": "IBCOri00058"
}

还要确认请求使用了接口要求的 HTTP 方法，例如 POST，并填写完整的接口地址。下面这个地址看起来只是服务器的基础地址：

https://developerapi.icicibank.com:8443

实际请求通常还需要接口路径。请从 ICICI 对应 API 的文档或 Portal 示例中复制完整 URL。

cURL 示例

假设完整接口地址为 <IMPS_API_PATH>，文档规定的 Header 名称是 API-Key，对应的请求可以写成：

curl --request POST \
  'https://developerapi.icicibank.com:8443/<IMPS_API_PATH>' \
  --header 'Content-Type: application/json' \
  --header 'API-Key: xxxxxxx' \
  --header 'Priority: 000000' \
  --data-raw '{
    "localTxnDtTime": "20200121160503",
    "beneAccNo": "057001510618",
    "beneIFSC": "ICIC0000570",
    "amount": "1",
    "tranRefNo": "17df6a44e57f436492f66f6",
    "paymentRef": "FTTransferP2A",
    "senderName": "APIGATEWAY",
    "mobile": "7588215033",
    "retailerCode": "rcode",
    "passCode": "d1118d6f9fe94696b4b1e1a0980bb396",
    "bcID": "IBCOri00058"
  }'

如果 ICICI 文档规定的字段名是 apikey，则改为：

apikey: xxxxxxx

不要根据页面标签自行猜测 Header 名称。可以查看 Developer Portal 生成的 cURL 示例，或通过浏览器开发者工具检查实际请求的 Headers。

仍然失败时的检查项

修正 Header 名称后，如果服务器返回认证错误或业务错误，可依次检查：

  1. API Key 是否属于当前测试环境。
  2. 是否使用了完整的接口 URL。
  3. HTTP 方法是否正确。
  4. 接口是否还要求签名、客户端证书、加密字段或其他认证 Header。
  5. 请求体格式是否符合接口要求。
  6. 当前来源 IP 是否需要加入白名单。
  7. Postman Web 版是否已经连接 Desktop Agent。

当前报错是客户端对 Header 格式的校验错误，与 IMPS 业务参数无关。先移除 API key 中的空格，再按照 ICICI 文档提供的实际 Header 字段名配置请求。

备注：内容仅供参考。