INRPay — 安全·快捷·可靠

INRPay 商户 API 对接文档

版本：v2.0（TP8 架构）

生成日期：2026-06-06

签名方式：HMAC-SHA256（旧版 MD5 已停用）

---

目录

1. 接入概览

2. 鉴权与签名

3. 代收下单

4. 代付下单

5. 代收回调

6. 代付回调

7. 错误码

8. 签名示例代码

9. 测试环境

---

1. 接入概览

重要： 商户回调地址在 商户后台 → API 设置 中配置，下单时不再传入 pay_notifyurl。

---

2. 鉴权与签名

2.1 身份标识

每个商户有一个 API memberid（公开ID），等于平台内部 ID + 10000。

在商户后台"API 设置"页面可查看。每笔请求必须携带此 ID。

2.2 HMAC-SHA256 签名算法

所有请求和回调均使用同一套签名算法。

步骤：

1. 取请求的全部参数（Key-Value 对）

2. 移除 sign 字段本身

3. 移除 value 为空字符串 "" 或 null 的字段

4. 将剩余字段按 Key 的 ASCII 升序 排列

5. 拼接成 key1=value1&key2=value2&... 形式的字符串（称为 canonical string）

6. 计算 HMAC-SHA256(canonical_string, hmac_secret)，取十六进制小写结果作为 sign

sign = lowercase( hex( hmac_sha256( canonical_string, hmac_secret ) ) )

canonical string 示例：

原始参数（无顺序要求）：

pay_memberid=220964988
pay_orderid=ORDER-20260606-001
pay_amount=500.00
pay_bankcode=413
attach=user123
sign=（本次要计算的，不参与签名）

按 key ASCII 排序后（忽略 sign）：

attach=user123&pay_amount=500.00&pay_bankcode=413&pay_memberid=220964988&pay_orderid=ORDER-20260606-001

然后对上述字符串计算 HMAC-SHA256，使用商户的 hmac_secret（64位十六进制字符串）作为密钥。

注意： value 中的数值类型不转换，原样拼接（如 500.00 就是 500.00，不要转成 500）。

2.3 验签（接收回调时）

收到平台回调后，同样按上述算法计算签名，与回调中的 sign 字段对比，完全相等则验签通过。

---

3. 代收下单

3.1 接口信息

3.2 请求参数

3.3 响应字段

{
  "status":       "success",
  "memberid":     "220964988",
  "order_no":     "20260606120000a1b2c3",
  "amount":       "500.0000",
  "duplicate":    false,
  "gateway_ok":   true,
  "redirect_url": "https://pay.upstream.com/checkout/xxxxx",
  "gateway_msg":  "",
  "sign":         "3ff6a28f..."
}

3.4 请求示例

POST /api/deposit/create HTTP/1.1
Content-Type: application/json
Content-Length: 234

{
  "pay_memberid":   "220964988",
  "pay_orderid":    "ORDER-20260606-001",
  "pay_amount":     "500.00",
  "pay_bankcode":   "413",
  "pay_applydate":  "20260606120000",
  "attach":         "user123",
  "sign":           "3ff6a28fbd40285b737d344acf677247209aa093cce2860cd0a7f2bb73a132b8"
}

---

4. 代付下单

4.1 接口信息

4.2 请求参数

字段命名变更（2026-06）：旧文档的 ifsc 字段已迁移到 pay_wttklist.ifscode；新增的 paymode 区分 bank 和 upi 两种支付通道。

4.3 响应字段

{
  "status":      "success",
  "memberid":    "220964988",
  "order_no":    "PO20260606120000a1b2c3",
  "amount":      "1000.0000",
  "paymode":     "bank",
  "duplicate":   false,
  "gateway_ok":  true,
  "gateway_msg": "",
  "sign":        "7a4c..."
}

4.4 请求示例

银行转账（paymode=bank）：

POST /api/payout/create HTTP/1.1
Content-Type: application/json
Content-Length: 197

{
  "pay_memberid": "220964988",
  "pay_orderid":  "PAYOUT-20260606-001",
  "pay_amount":   "1000.00",
  "paymode":      "bank",
  "bank_account": "9876543210",
  "bank_name":    "SBI",
  "bank_holder":  "Raj Kumar",
  "ifscode":      "SBIN0001234",
  "sign":         "..."
}

UPI 支付（paymode=upi）：

POST /api/payout/create HTTP/1.1
Content-Type: application/json
Content-Length: 170

{
  "pay_memberid": "220964988",
  "pay_orderid":  "PAYOUT-20260606-002",
  "pay_amount":   "500.00",
  "paymode":      "upi",
  "bank_account": "merchant@upi",
  "bank_name":    "HDFC",
  "bank_holder":  "Merchant",
  "ifscode":      "",
  "sign":         "..."
}

签名错误响应：

{ "status": "fail", "msg": "sign error" }

参数校验失败：

{ "status": "fail", "msg": "ifscode must be 11 chars with 5th char = 0 (e.g. SBIN0001234)" }

或

{ "status": "fail", "msg": "paymode must be \"bank\" or \"upi\"" }

---

5. 代收回调

5.1 触发条件

上游网关确认支付成功后，平台异步将结果 POST 到商户在后台配置的 代收回调地址（deposit_callback_url）。

5.2 回调参数（POST，application/json）

5.3 商户响应要求

商户服务器处理完成后，必须返回纯文本字符串 ok（不区分大小写，忽略前后空白），HTTP 状态码 200。

HTTP/1.1 200 OK
Content-Type: text/plain

ok

若未收到 ok，平台按以下间隔自动重试，最多 5 次：

5 次全部失败后不再重试，可在管理后台 Callbacks 页面查看失败记录并手动处理。

5.4 回调示例

POST https://your-server.com/deposit/notify HTTP/1.1
Content-Type: application/json
Content-Length: 197

{
  "memberid":      "220964988",
  "orderid":       "ORDER-20260606-001",
  "transaction_id":"20260606120000a1b2c3",
  "amount":        "500.0000",
  "datetime":      "20260606121530",
  "returncode":    "00",
  "attach":        "user123",
  "sign":          "3ff6a28f..."
}

---

6. 代付回调

6.1 触发条件

上游网关反馈代付结果（成功或失败）后，平台异步 POST 到商户的 代付回调地址（payout_callback_url）。

6.2 回调参数（POST，application/json）

6.3 商户响应要求

同代收回调，返回 ok 确认收到。重试策略相同（1m / 5m / 30m / 2h / 12h，最多 5 次）。

---

7. 错误码

7.1 HTTP 层面错误（鉴权失败，请求未到达业务逻辑）

7.2 业务层面错误（HTTP 400）

---

8. 签名示例代码

PHP

function hmac_sign(array $params, string $secret): string {
    // 1. 移除 sign 字段
    unset($params['sign']);
    // 2. 移除空值
    $params = array_filter($params, fn($v) => $v !== '' && $v !== null);
    // 3. ASCII 升序排列
    ksort($params, SORT_STRING);
    // 4. 拼接 canonical string
    $canonical = implode('&', array_map(
        fn($k, $v) => $k . '=' . $v,
        array_keys($params), array_values($params)
    ));
    // 5. 计算 HMAC-SHA256
    return hash_hmac('sha256', $canonical, $secret);
}

// 使用示例
$params = [
    'pay_memberid' => '220964988',
    'pay_orderid'  => 'ORDER-20260606-001',
    'pay_amount'   => '500.00',
    'pay_bankcode' => '413',
    'attach'       => 'user123',
];
$params['sign'] = hmac_sign($params, 'your_hmac_secret_here');

// 发起请求
$ch = curl_init('https://your-domain.com/api/deposit/create');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Python

import hmac, hashlib, requests

def hmac_sign(params: dict, secret: str) -> str:
    p = {k: v for k, v in params.items() if k != 'sign' and v not in ('', None)}
    canonical = '&'.join(f"{k}={v}" for k, v in sorted(p.items()))
    return hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()

params = {
    'pay_memberid': '220964988',
    'pay_orderid':  'ORDER-20260606-001',
    'pay_amount':   '500.00',
    'pay_bankcode': '413',
    'attach':       'user123',
}
params['sign'] = hmac_sign(params, 'your_hmac_secret_here')

resp = requests.post(
    'https://your-domain.com/api/deposit/create',
    json=params,                # requests 会自动设置 Content-Type: application/json
)
print(resp.json())

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;

public static String hmacSign(Map<String, String> params, String secret) throws Exception {
    params.remove("sign");
    // 移除空值
    params.entrySet().removeIf(e -> e.getValue() == null || e.getValue().isEmpty());
    // ASCII 升序
    TreeMap<String, String> sorted = new TreeMap<>(params);
    StringBuilder sb = new StringBuilder();
    for (Map.Entry<String, String> e : sorted.entrySet()) {
        if (sb.length() > 0) sb.append('&');
        sb.append(e.getKey()).append('=').append(e.getValue());
    }
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
    byte[] raw = mac.doFinal(sb.toString().getBytes("UTF-8"));
    StringBuilder hex = new StringBuilder();
    for (byte b : raw) hex.append(String.format("%02x", b));
    return hex.toString();
}

回调验签（PHP）

function verify_callback(array $body, string $secret): bool {
    $given = $body['sign'] ?? '';
    return hash_equals(hmac_sign($body, $secret), strtolower($given));
}

// 接收回调：直接读原始 POST body 并 json_decode
$raw = file_get_contents('php://input');
$body = json_decode($raw, true);
if (!is_array($body) || !verify_callback($body, 'your_hmac_secret_here')) {
    http_response_code(400);
    exit('sign error');
}
// 处理业务逻辑（金额字段都是字符串，按需用 (float) 转）
if ($body['returncode'] === '00') {
    update_order($body['orderid'], 'paid', (float) $body['amount']);
}
echo 'ok'; // 必须返回 ok

---

9. 测试环境

9.1 连接信息

9.2 测试商户凭据

⚠️ 仅限本地开发环境使用，切勿用于生产。

9.3 签名调试端点

平台提供一个调试端点，输入参数后返回 canonical string 和 sign，方便排查签名问题：

GET/POST /api/diag/sign?pay_memberid=220964988&pay_orderid=TEST-001&pay_amount=100.00&...

响应示例：

{
  "canonical": "pay_amount=100.00&pay_memberid=220964988&pay_orderid=TEST-001",
  "sign": "计算出的签名"
}

9.4 代收流程完整测试步骤

1. 启动服务器和队列 Worker

2. 调用 POST /api/deposit/create 创建订单，记录响应中的 order_no 和 redirect_url

3. 模拟上游回调：POST /api/notify/show/deposit（见 Mock 接口）

4. 观察商户的 deposit_callback_url 是否收到回调（returncode=00）

5. 回调日志在管理后台 Callbacks 页可查看

---

附录：接口地址汇总

旧版 URL（兼容保留，实际请求仍走新逻辑）：

- /Pay_Show_notifyurl.html — Show 渠道代收上游回调

- /Payment_Show_dfnotify.html — Show 渠道代付上游回调