商户接口对接文档

01概览

Titan Pay 的商户接口分四组：代收、代付、账户和回调。身份是 X-Titan-Key 加一把密钥，所有业务接口都走同一个 Host，只接受 POST 和 JSON。

先记住四条约定

1. 身份在请求头。 X-Titan-Key、X-Titan-Timestamp、X-Titan-Nonce、X-Titan-Signature 四个字段不进 JSON；密钥由 X-Titan-Key 定位。
2. 金额永远是整数分。 100.00 卢比写成 10000，不接受小数、字符串或科学计数法。
3. 幂等键是商户订单号。 超时或断网时保持 orderNo 不变重试，换一个新的 X-Titan-Nonce，不要新建订单号。
4. 回调是平台调你。 只为 PAID、FAILED、RETURNED、AMOUNT_MISMATCH 发送；PENDING、UNPAID、EXPIRED 不发。

02接入准备

开通后你会拿到一组商户资料。联调与生产共用同一把密钥，平台切换模式后，原来的密钥自动操作正式账套。

从沙箱到生产

1. 在 Telegram 领取沙箱密钥，先调用 余额查询 验证签名，响应里 mode 应为 test。
2. 创建一笔 1 卢比的代收，用 沙盒模拟 把它推进到 PAID，确认回调、验签和入账逻辑都能跑通。
3. 把失败路径也跑一遍：FAILED、AMOUNT_MISMATCH、回调超时后主动查单。
4. 确认费率、单笔/单日限额、结算批次和 IP 白名单，再由平台把商户切到生产。

03鉴权与签名

每个请求带四个请求头。签名是对五行规范串做 HMAC-SHA256，输出小写十六进制。任何一个空格、字段顺序或时间戳变化，签名都会失效。

规范串

五行用换行符 \n 连接，最后一行后面不加换行：

HTTP_METHOD
PATH
TIMESTAMP
NONCE
SHA256_HEX(rawBody)

• HTTP_METHOD 大写，固定为 POST。
• PATH 只取路径，不带域名和查询串，例如 /v1/collect。
• TIMESTAMP、NONCE 与请求头中的值逐字符一致。
• rawBody 是实际发送的原始字节。先序列化再签名，发送时不要重新格式化，也不要加 BOM。
• 请求体最大 64 KiB，且必须是 JSON 对象；Content-Type 以 application/json 开头。

可复核的签名样本

下面这组输入可以在本地复算，密钥 test-secret 只用于说明算法，不是任何商户的真实密钥。

POST
/v1/balance
1760140800
n-example1
44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a

服务端签名示例

import hashlib, hmac, json, time, uuid

MERCHANT_NO = "1042"
SECRET = "test-secret"
path = "/v1/collect"

body = {
    "orderNo": "M202610110001",
    "amount": 10000,
    "callbackUrl": "https://merchant.example/notify",
}
raw = json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode()

ts = str(int(time.time()))
nonce = uuid.uuid4().hex[:16]
canonical = "\n".join([
    "POST", path, ts, nonce,
    hashlib.sha256(raw).hexdigest(),
])
signature = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()

import crypto from "node:crypto";

const secret = "test-secret";
const path = "/v1/collect";
const body = { orderNo: "M202610110001", amount: 10000 };
const raw = JSON.stringify(body);

const ts = String(Math.floor(Date.now() / 1000));
const nonce = crypto.randomBytes(8).toString("hex");
const canonical = [
  "POST", path, ts, nonce,
  crypto.createHash("sha256").update(raw).digest("hex"),
].join("\n");

const signature = crypto
  .createHmac("sha256", secret)
  .update(canonical)
  .digest("hex");

用固定样本调一次

下面这条请求用的是上面的固定时间戳，线上会返回 TIMESTAMP_EXPIRED，只适合本地核对签名实现。真实请求换成当前秒级时间戳。

curl -sS https://open.titantg.in/v1/balance \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'X-Titan-Key: 1042' \
  -H 'X-Titan-Timestamp: 1760140800' \
  -H 'X-Titan-Nonce: n-example1' \
  -H 'X-Titan-Signature: 2e6150e3633d0d2d682a08d4585375fefdef1d9bbb8159e0f3b6787aceacdb54' \
  -d '{}'

04代收

代收负责「收款」：创建订单拿付款页或 UPI 意图链接，支付结果通过回调或查询确认。创建成功只代表受理，此时状态是 PENDING。

{
  "orderNo": "M202610110001",
  "amount": 10000,
  "callbackUrl": "https://merchant.example/notify",
  "redirectUrl": "https://merchant.example/return"
}

{
  "code": "OK",
  "message": "success",
  "data": {
    "orderNo": "M202610110001",
    "tradeNo": "TX17601408001234ab",
    "status": "PENDING",
    "amount": 10000,
    "payUrl": "https://pay.example/cashier/TX17601408001234ab",
    "vpa": "merchant@upi",
    "intentUri": "upi://pay?pa=merchant%40upi&am=100.00&cu=INR"
  }
}

05UTR 与 UPI

银行侧已经到账、但回调丢失或人工补录时，用 UTR 接口核对与补单；不确定一个 UPI 是否属于本平台时，用归属查询。

06代付

代付负责「出款」：创建即冻结当前模式下的可用余额，成功后扣减。可用余额不足返回 INSUFFICIENT_BALANCE，联调账户未开通返回 ACCOUNT_NOT_FOUND。

{
  "orderNo": "P202610110001",
  "amount": 10000,
  "ifsc": "HDFC0001234",
  "holderName": "Rahul",
  "cardNumber": "123456789012",
  "callbackUrl": "https://merchant.example/payout-notify"
}

{
  "code": "OK",
  "message": "success",
  "data": {
    "orderNo": "P202610110001",
    "tradeNo": "TX17601408001234ab",
    "status": "CREATED",
    "amount": 10000,
    "available": 89170
  }
}

07账户与沙盒

余额接口用来确认密钥、模式和账套；沙盒模拟接口用来在没有真实付款的情况下把测试订单推进到终态，验证回调链路。

{
  "code": "OK",
  "message": "success",
  "data": {
    "merchantNo": "1042",
    "mode": "test",
    "available": 89170,
    "frozen": 10830,
    "balance": 100000
  }
}

08回调通知

回调是平台调用商户，不是商户调用平台。订单进入终态后，平台向该笔订单的 callbackUrl 发 POST；你只需要回一段约定的确认正文。

何时发送

• 只为 PAID、FAILED、RETURNED、AMOUNT_MISMATCH 发送，代付的退回和金额不符也会回调。
• PENDING、UNPAID、EXPIRED 不发通知。
• 同一次结果不会因为重复查询而再次发送；只有把订单推进到相反终态才会产生另一条通知。

通知字段

验签

平台用该商户的接口密钥，按与商户请求相同的算法签名。PATH 取通知地址的路径，请求头仍是 X-Titan-Key、X-Titan-Timestamp、X-Titan-Nonce、X-Titan-Signature。请用自己保存的密钥验签，并确认 X-Titan-Key 是自己的编号。

确认正文

• 只比较响应正文：去掉首尾空白后等于 ok，即视为已送达；不看 HTTP 状态码。
• 返回纯文本 ok，不要另包一层 JSON。
• 没有返回 ok、超时或连接失败时，会按覆盖 24 小时的退避重试，然后进入死信。
• 确认要做幂等：同一 tradeNo、同一状态的重复通知不要重复入账。

POST /notify HTTP/1.1
Host: merchant.example
Content-Type: application/json; charset=UTF-8
X-Titan-Key: 1042
X-Titan-Timestamp: 1760140800
X-Titan-Nonce: n-callback1
X-Titan-Signature: <lowercase-hex-hmac>

{
  "kind": "collect",
  "merchantNo": "1042",
  "orderNo": "M202610110001",
  "tradeNo": "TX17601408001234ab",
  "status": "PAID",
  "amount": 10000,
  "paidAmount": 10000,
  "bankRef": "123456789012",
  "vpa": "merchant@upi"
}

ok

09错误码

失败时按 code 分支判断，message 只用于排查和日志。错误码与 HTTP 状态一一对应。

{
  "code": "AMOUNT_INVALID",
  "message": "invalid amount",
  "data": null,
  "requestId": "8f2c1d7a9b4e4f0e"
}

重试策略

• 429 与 5xx 可以退避重试，保持 orderNo 不变，并换新 X-Titan-Nonce。
• 其余 4xx 是请求本身的问题，重试不会成功，按 message 和 code 修字段。
• SIGNATURE_INVALID 不要暴露给付款人，也不要在响应里回显密钥或签名串。

10上线检查

生产切换前，把下面几项逐条跑通。任何一项没确认，都建议继续留在沙箱。

• 用页面上的 test-secret 样本复算出同一个签名，确认编码、换行和时间戳都正确。
• 所有金额都按整数分发送，数据库里没有用浮点数存金额。
• 超时重试保持同一个 orderNo，每次换新 X-Titan-Nonce，并正确处理 Idempotent-Replayed。
• 回调先验签，再按 tradeNo + status 做幂等，重复通知不会重复入账。
• 回调返回纯文本 ok；测过错误正文会触发重试。
• 回调静默或超时时先查单，不重建订单；UNPAID 不当失败处理。
• IP 白名单、单笔/单日限额、默认回调地址和确认正文已在商户资料里确认。
• 先按 5% 流量灰度，盯成功率和回调延迟，再按 20% 递增；结算文件与 UTR 逐笔对得上。