1. 敏捷时代的支付安全

在构建电商收银台、聚合支付或转账功能时，前端往往需要快速获得反馈：“这张卡能用吗？”后端则需要确保资金合规：“这张卡涉案吗？”

Node.js 是连接这两端的最佳桥梁。利用 天远银行卡黑名单(实时)接口，我们可以在 Node.js 中间层（BFF）快速拦截高危卡片。无论用户提交的是“涉案卡”还是“欺诈交易卡”，接口都能在毫秒级返回 “1” (命中) 标签 ，帮助开发者将风险阻挡在资金清算之前。

2. API 调用实战：原生 Crypto 模块的优雅实现

Node.js 内置的 crypto 模块完美支持 AES-128-CBC 算法，无需引入笨重的第三方库。我们将演示如何封装一个通用的 RiskClient 类，处理 IV 拼接与 Base64 编码。

2.1 依赖安装

推荐使用 axios 处理 HTTP 请求：

Bash

npm install axios

2.2 完整代码实现 (Async/Await)

该示例包含完整的加解密流程，自动处理了 PKCS7 填充（Node.js crypto 默认行为）。

JavaScript

const axios = require('axios');
const crypto = require('crypto');

class BankCardRiskClient {
    constructor(accessId, accessKeyHex) {
        // 接口地址: 银行卡黑名单(实时)接口
        this.apiUrl = 'https://api.tianyuanapi.com/api/v1/JRZQ0B6Y'; [cite_start]// [cite: 6]
        this.accessId = accessId;
        // 关键: 将16进制字符串转为 Buffer
        this.accessKey = Buffer.from(accessKeyHex, 'hex'); [cite_start]// [cite: 6]
    }

    /**
     * 加密: 生成随机IV -> AES加密 -> 拼接IV -> Base64
     */
    encrypt(data) {
        const iv = crypto.randomBytes(16); [cite_start]// 16字节随机IV [cite: 6]
        const cipher = crypto.createCipheriv('aes-128-cbc', this.accessKey, iv);
        
        // JSON 序列化
        const plainText = JSON.stringify(data);
        
        // update + final 完成加密 (自动 PKCS7 填充)
        let encrypted = cipher.update(plainText, 'utf8');
        encrypted = Buffer.concat([encrypted, cipher.final()]);

        // 拼接 IV + 密文
        const combined = Buffer.concat([iv, encrypted]);
        
        return combined.toString('base64'); [cite_start]// [cite: 6]
    }

    /**
     * 解密: Base64解码 -> 提取IV -> 解密
     */
    decrypt(base64Data) {
        const buffer = Buffer.from(base64Data, 'base64');

        // 提取前 16 字节作为 IV
        const iv = buffer.slice(0, 16); [cite_start]// [cite: 6]
        const text = buffer.slice(16);

        const decipher = crypto.createDecipheriv('aes-128-cbc', this.accessKey, iv);
        let decrypted = decipher.update(text);
        decrypted = Buffer.concat([decrypted, decipher.final()]);

        return JSON.parse(decrypted.toString());
    }

    /**
     * 发起黑名单查询
     */
    async checkCard(name, idCard, mobile, bankCard) {
        try {
            // 1. 准备数据
            const payload = { 
                name, 
                id_card: idCard, 
                mobile_no: mobile, 
                bank_card: bankCard 
            }; [cite_start]// [cite: 6]

            // 2. 加密
            const encryptedData = this.encrypt(payload);

            // 3. 发送请求 (注意时间戳 t)
            const response = await axios.post(
                this.apiUrl, 
                { data: encryptedData }, 
                {
                    headers: { 'Access-Id': this.accessId },
                    [cite_start]params: { t: Date.now() } // [cite: 6]
                }
            );

            const resData = response.data;

            if (resData.code === 0) {
                // 4. 解密响应
                return this.decrypt(resData.data);
            } else {
                console.error(`API 错误: ${resData.message} (${resData.code})`);
                return null;
            }
        } catch (error) {
            console.error('请求失败:', error.message);
            return null;
        }
    }
}

// --- 使用示例 ---
(async () => {
    // ⚠️ 请使用环境变量存储密钥，勿硬编码
    const client = new BankCardRiskClient(
        process.env.ACCESS_ID || 'YOUR_ID', 
        process.env.ACCESS_KEY || 'YOUR_HEX_KEY'
    );

    const riskReport = await client.checkCard(
        '王五', 
        '33010619880101xxxx', 
        '13900000000', 
        '622202020011xxxx'
    );

    if (riskReport) {
        console.log('--- 风险检测报告 ---');
        [cite_start]console.log('涉案卡片:', riskReport.caseRelated === '1' ? '⚠️ 是' : '否'); // [cite: 6]
        console.log('交易欺诈:', riskReport.fraudTrans === '1' ? '⚠️ 是' : '否'); [cite_start]// [cite: 6]
        console.log('原始数据:', riskReport);
    }
})();

3. 核心数据结构解析：JS 对象的类型陷阱

在 JavaScript 中处理 API 响应时，最大的坑在于类型转换。接口返回的所有标志位均为 字符串 形式的 “1” 或 “0” 。

3.1 关键字段清洗建议

建议在 Service 层将 API 的原始数据清洗为 Boolean 值，方便业务逻辑判断。

原始字段 (String)	含义	建议清洗逻辑 (JS)
caseRelated	涉案卡片	const isCriminal = res.caseRelated === '1'
fraudTrans	交易欺诈	const isFraud = res.fraudTrans === '1'
badCardHolder	不良持卡人	const isBadUser = res.badCardHolder === '1'

注意：千万不要写 if (res.caseRelated)，因为非空字符串 “0” 在 JS 中也是 true，这会导致严重误判！

4. 应用价值：Serverless 与低成本风控

Node.js 的轻量级特性使其非常适合部署在 AWS Lambda 或 阿里云函数计算 上，构建按量付费的风控服务。

4.1 场景：API 网关前置拦截

利用 Serverless 云函数作为支付接口的“前置守卫”。

• 流程：用户请求 -> API 网关 -> Node.js 风控云函数 (调用天远 API) -> 业务服务器。
• 优势：若云函数检测到 caseRelated="1"，直接抛出 403 拒绝，流量根本不打到核心业务服务器，保护了核心系统的安全，且 Serverless 只有在调用时才计费，成本极低。

4.2 场景：批量 Excel 导入清洗

财务部门经常需要批量打款。可以使用 Node.js 的 Stream 流式处理，读取 Excel/CSV 文件，并发调用 API 进行清洗。

• 技巧：使用 Promise.all 控制并发度（如每次 5 个），防止瞬间 QPS 过高。

5. 总结

Node.js + 天远银行卡黑名单 API，是构建灵活性与安全性兼备的支付系统的理想选择。通过仅几十行代码，我们就能利用 AES 加密技术，接入国家级的金融风险名单库，为企业的每一笔资金流动保驾护航。

---

对接规范与隐私合规重要提示

在享受天远 API 带来的风控便利时，开发者必须时刻绷紧“安全与合规”这根弦。由于本接口涉及姓名、身份证号、银行卡号等高敏感个人信息，请务必严格遵守以下规范：

1. 接口对接安全：
   • 密钥保护：严禁将 Access-Id 和 Access-Key 硬编码在前端代码或公开的代码仓库中。请务必存储在服务器端的环境变量或密钥管理服务中。
   • 传输加密：本接口强制要求使用 HTTPS 加密传输，且请求体必须通过 AES-128 算法加密。请勿尝试绕过加密机制直接发送明文数据，以防止中间人攻击。
2. 个人隐私与合规：
   • 合法授权：在调用本接口查询用户黑名单状态前，必须获得用户的明确授权。请在您的《隐私政策》或服务协议中明确告知用户，您将使用第三方数据服务进行风险评估。
   • 数据最小化：仅在业务必要时调用接口。建议对接口返回的敏感结果（如涉案标签）进行脱敏存储，并设置严格的数据访问权限。
   • 合规遵从：请确保您的业务场景符合《个人信息保护法》及相关反洗钱法规的要求，不得将本接口用于非法的数据买卖或非授权的背景调查。