快速开始
3 分钟接入金牛钱包 API。下面以「查询余额」为例，展示完整流程。
1
登录控制台创建 API 密钥
访问 个人中心 → API 密钥，点击「创建密钥」。
填写名称、选择 scope（如「查询」）、可选配置 IP 白名单和速率限制。创建后会得到 jk_xxx（公开 ID）和 sk_xxx（私密 Secret）。
Secret 仅展示一次！关闭弹窗后无法再次查看，请立即保存到安全位置。
2
构造签名
使用 HMAC-SHA256 对 key_id + timestamp + nonce 拼接串做签名。
3
发送请求
将 5 个 Header 附加到请求中，调用接口即可。
完整示例 · 查询余额
PHP 示例：
<?php
// 1. 准备密钥（从控制台获取）
$keyId = "jk_xxxxxxxxxxxxxxxx";
$secret = "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
// 2. 生成签名材料
$timestamp = time();
$nonce = bin2hex(random_bytes(8));
$signature = hash_hmac("sha256", $keyId . $timestamp . $nonce, $secret);
// 3. 发送请求
$ch = curl_init("https://pay.jnqj.net/api/v1/balance");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-JNQJ-Key: " . $keyId,
"X-JNQJ-Secret: " . $secret,
"X-JNQJ-Timestamp: " . $timestamp,
"X-JNQJ-Nonce: " . $nonce,
"X-JNQJ-Signature: " . $signature,
],
CURLOPT_TIMEOUT => 30,
CURLOPT_SSL_VERIFYPEER => true,
]);
$resp = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
// 4. 解析响应
$data = json_decode($resp, true);
if ($data["ok"] ?? false) {
echo "当前余额：¥" . number_format($data["data"]["balance"], 2);
} else {
echo "请求失败：" . ($data["msg"] ?? "未知错误");
}
Node.js 示例：
// npm install node-fetch
const crypto = require("crypto");
const fetch = require("node-fetch");
const keyId = "jk_xxxxxxxxxxxxxxxx";
const secret = "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const timestamp = Math.floor(Date.now() / 1000);
const nonce = crypto.randomBytes(8).toString("hex");
const signature = crypto.createHmac("sha256", secret)
.update(keyId + timestamp + nonce)
.digest("hex");
fetch("https://pay.jnqj.net/api/v1/balance", {
headers: {
"X-JNQJ-Key": keyId,
"X-JNQJ-Secret": secret,
"X-JNQJ-Timestamp": timestamp,
"X-JNQJ-Nonce": nonce,
"X-JNQJ-Signature": signature,
},
})
.then(r => r.json())
.then(d => console.log(d.ok ? "余额：" + d.data.balance : "失败：" + d.msg))
.catch(e => console.error(e));
curl 示例（适合调试）：
# 先用 shell 计算签名
KEY_ID="jk_xxxxxxxxxxxxxxxx"
SECRET="sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 8)
SIGNATURE=$(printf "%s%s%s" "$KEY_ID" "$TIMESTAMP" "$NONCE" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl https://pay.jnqj.net/api/v1/balance \
-H "X-JNQJ-Key: $KEY_ID" \
-H "X-JNQJ-Secret: $SECRET" \
-H "X-JNQJ-Timestamp: $TIMESTAMP" \
-H "X-JNQJ-Nonce: $NONCE" \
-H "X-JNQJ-Signature: $SIGNATURE"
幂等性示例
对于写接口（/collection 和 /refund），建议每次请求都携带 X-Idempotency-Key 头，
避免因网络重试导致重复扣款。
# 同一 idempotency_key 在 10 分钟内重复请求，会返回首次的响应
curl -X POST https://pay.jnqj.net/api/v1/collection \
-H "X-JNQJ-Key: $KEY_ID" \
-H "X-JNQJ-Secret: $SECRET" \
-H "X-JNQJ-Timestamp: $TIMESTAMP" \
-H "X-JNQJ-Nonce: $NONCE" \
-H "X-JNQJ-Signature: $SIGNATURE" \
-H "X-Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"amount": 100.00, "merchant_id": 1}'
完成！你已经掌握了金牛支付 API 的全部基础知识。完整端点详情请查阅「所有端点」。