发卡宝 / 卡密中心 - API 接口文档

POST 1. 卡密状态预览 (check)

用于前端页面不扣款的实时校验。当用户输入完卡密离开焦点时，可提前拦截错误卡密并向用户展示即将充值的卡种信息。

请求参数 (JSON Body)

参数名	类型	必填	说明
`apikey`	String	是	商户唯一身份密钥
`method`	String	是	固定为 `"check"`
`cardNo`	String	是	17位待查验的卡密文本

💡 请求报文示例

{
    "apikey": "b3b44b8277259169",
    "method": "check",
    "cardNo": "ABCDE-26WTE-23DFD "
}

✅ 成功响应 (code = 1)

{
    "code": 1,
    "data": {
        "pid": 24,
        "status": "unused"
    }
}

POST 2. 卡密原子核销 (setUsed)

核心扣款接口。采用独占数据库锁机制，检查与核销一步到位。能从根本上消除高并发下恶意刷卡的可能。核销成功后返回关联的 pid。

请求参数 (JSON Body)

参数名	类型	必填	说明
`apikey`	String	是	商户唯一身份密钥
`method`	String	是	固定为 `"setUsed"`
`cardNo`	String	是	17位要执行扣减核销的卡密文本

💡 请求报文示例

{
    "apikey": "b3b44b8277259169",
    "method": "setUsed",
    "cardNo": "ABCDE-26WTE-23DFD "
}

✅ 成功响应 (code = 1)

{
    "code": 1,
    "data": {
        "msg": "核销成功",
        "pid": 26
    }
}

❌ 失败/已被占用响应 (code = 0)

{
    "code": 0,
    "msg": "充值失败：卡密不存在或已被使用"
}

PHP SDK 后端调用代码示例 (Demo)

以下为您提供生产环境推荐的 PHP 原生 cURL 调用封装，包含错误捕获、超时预防、Header 头设置以及规范的 JSON 解析逻辑。

🐘 完整 PHP 代码（直接复制使用）

<?php
/**
 * 卡密中心核心调用工具类
 */
class CardCenterSDK {
    private $apiKey = "b3b44b8277259169"; // 您的商户API密钥
    private $apiUrl = "https://fakabao.net/api/index.php"; // 接口地址

    /**
     * 发送原子级核销请求
     * @param string $cardNo 17位卡密
     * @return array ['success' => bool, 'pid' => int, 'message' => string]
     */
    public function consumeCard($cardNo) {
        // 1. 组装符合文档规范的 JSON 载荷
        $payload = json_encode([
            'apikey' => $this->apiKey,
            'method' => 'setUsed', // 核心原子核销方法
            'cardNo' => trim($cardNo)
        ], JSON_UNESCAPED_UNICODE);

        // 2. 初始化 cURL
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->apiUrl);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        // 关键：必须声明内容格式为 JSON
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json; charset=UTF-8',
            'Content-Length: ' . strlen($payload)
        ]);
        
        // 健壮性设置：防止卡死，设置10秒超时
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);
        curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
        
        // 生产环境安全设置：如果是 HTTPS 建议开启，此处 localhost 暂不校验
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

        // 3. 执行请求
        $response = curl_exec($ch);
        $errorNo  = curl_errno($ch);
        $errorMsg = curl_error($ch);
        curl_close($ch);

        // 4. 处理网络级网络错误
        if ($errorNo) {
            return [
                'success' => false, 
                'pid'     => 0, 
                'message' => "网络通讯失败: " . $errorMsg
            ];
        }

        // 5. 解析返回的 JSON
        $result = json_decode($response, true);
        if (empty($result)) {
            return [
                'success' => false, 
                'pid'     => 0, 
                'message' => "卡密中心响应异常或无法解析"
            ];
        }

        // 6. 根据接口 code 状态码进行业务分发
        if ((int)($result['code'] ?? 0) === 1) {
            return [
                'success' => true,
                'pid'     => (int)($result['data']['pid'] ?? 0),
                'message' => $result['data']['msg'] ?? '核销成功'
            ];
        } else {
            return [
                'success' => false,
                'pid'     => 0,
                'message' => $result['msg'] ?? '未知扣款失败错误'
            ];
        }
    }
}

// ==================== 🛠️ 使用示例 ====================

// 实例化 SDK
$sdk = new CardCenterSDK();

// 模拟接收前端传递的用户卡密
$inputCard = "ABCDE-26WTE-23DFD"; 

// 执行扣减
$res = $sdk->consumeCard($inputCard);

if ($res['success']) {
    echo "🎉 扣款核销成功！<br>";
    echo "产品 PID: " . $res['pid'] . "<br>";
    echo "提示信息: " . $res['message'] . "<br>";
    
    // TODO: 在此处编写本地系统的给用户加 VIP 时间的逻辑
    // switch($res['pid']) { ... }

} else {
    echo "❌ 核销失败！<br>";
    echo "失败原因: " . $res['message'] . "<br>";
}
?>