API 接口文档

发卡宝 API v1 只有两个接口：幂等核销（consume）与对账查询（query）。

签名规则

POST: Sign = HMAC_SHA256( Secret, Timestamp + "." + 请求体原文(raw body) )
GET : Sign = HMAC_SHA256( Secret, Timestamp + "." + URL查询串原文(QUERY_STRING) )

要点：
1. POST 参与签名的是"实际发出的字节"——先 json_encode 得到 $body，签名用 $body，发送也用 $body，中间不得重排/格式化；
2. GET 的查询串自行拼接（如 http_build_query 的结果），签什么就发什么，避免 curl/代理二次编码改变顺序；
3. 签名失败返回 401 INVALID_SIGN，可用示例 Demo 对照排查。

行锁原子操作：校验 + 登记台账 + 标记已用一次完成，是整条链路唯一需要同步等待的调用（建议连接 3s / 总 6s 超时）。幂等：同 clientTxnId 重放返回相同结果。

请求参数（JSON Body）

POST /api/index.php
Content-Type: application/json
X-API-Key: 9ffa60a9c4aa4eb512312d680e2974dc
X-Timestamp: 1789502400
X-Sign: hmac_sha256(secret, "1789502400." + 请求体原文)

{"method":"consume","cardNo":"BQ7WK-T9U4W-NGRTJ","clientTxnId":"20260916032156_3f9a27de01c8b4f5"}

查询核销台账，供超时收敛、定时对账、人工补单前核对。先按 clientTxnId 查，未命中自动回落按 cardNo 查（并可追溯卡表兜底），单参数也可查，两个都带最稳。

GET /api/index.php?clientTxnId=20260916032156_3f9a27de01c8b4f5
（签名原文 = Timestamp + "." + "clientTxnId=20260916032156_3f9a27de01c8b4f5"）

已核销：{"code":1,"data":{"used":true, "pid":38,"usedTxn":"20260916032156_3f9a27de01c8b4f5","usedAt":"2026-09-16 03:21:56"}}
未核销：{"code":1,"data":{"used":false,"pid":0, "usedTxn":"","usedAt":""}}

平台不提供自动回滚（卡状态单调向前）。“本地没办成”的兜底不是退卡，而是本地重试发放。

1 本地落单 pending（生成 clientTxnId，落库成功后才发请求）
2 POST consume（唯一同步阻塞，1 次 HTTP）
   ├─ code=1 → 3
   ├─ NOT_FOUND / ALREADY_USED / REFUNDED → 订单 failed，提示换卡
   └─ 超时 / 429 / BUSY / 5xx / 鉴权错 → 保持 pending，返回"处理中"
3 本地事务：按 pid 发放权益 + 订单翻 success（同一事务，原子只翻转一次）
4 定时任务（每分钟）：扫 pending 超时单 → GET query
   ├─ used=false 超30分钟 → failed（用户可复用原单号重提）
   ├─ used=true  usedTxn==本单 → 补执行第3步（自愈）
   └─ used=true  usedTxn!=本单 → 转人工，禁止发放
5 客服通道：误核销人工 refund，卡恢复可用；你的历史单号再重放会收到 REFUNDED

<?php
require 'FakabaoClient.php';   // 下载见下方「官方 PHP SDK」

$c    = new FakabaoClient('https://www.fakabao.net', '你的KEY', '你的SECRET');
$card = 'ABCDE-FGHIJ-KLMNO';

$txn = FakabaoClient::newTxnId();   // 自动生成，无需商户号
// TODO 先把 $txn 以 pending 写入你自己的订单表，再发起核销（重试/对账复用，禁止重新生成）

try {
    $r = $c->consume($card, $txn);   // ['pid'=>38,'replay'=>false]
    // TODO 本地事务：按 $r['pid'] 发放权益 + 订单翻 success（同一事务，只翻转一次）
} catch (FakabaoException $e) {
    if ($e->isRetryable()) {
        // TIMEOUT/BUSY/RATE_LIMITED/BAD_RESPONSE/5xx：保持 pending，
        // 前端文案"处理中，1分钟后自动到账"，定时任务调 query 收敛
    } else {
        // NOT_FOUND / ALREADY_USED / REFUNDED：终态失败，订单置 failed，提示换卡
    }
}

// 定时任务：对账 pending 超时单
$q = $c->query($card, $txn);         // ['used','pid','usedTxn','usedAt']
if ($c->isUsedByMe($card, $txn)) { /* 唯一允许自动补发的情况 */ }
?>

已封装签名、超时语义、错误分类与补发核对，含充值闭环 + reconcile 模板。

⬇ 下载 PHP SDK fakabao-sdk-php.zip