Guides
  1. Getting Started

快速开始

5 分钟跑通你的第一个 CAFINX 开放接口请求

快速开始

API 文档 v1.8 · 更新于 2026-08
Base URL：沙箱 https://uat-openapi.cafinx.com/v1 · 生产 https://openapi.cafinx.com/v1

CAFINX 开放接口让你以商户身份程序化管理虚拟卡：开卡、充值、转出、冻结/销卡、共享卡组、查询交易与钱包流水，并接收 Webhook 异步事件。本页帮你在几分钟内跑通第一个请求。

开卡提示：并非所有卡产品都需要身份认证。请先 GET /card-products 看该 bin 的 requireThirdPartyKyc。
详见 卡产品与身份认证。

安全声明（摘要）

完整条款见控制台 API 文档侧栏「安全声明」或下文约定。要点：

  • 密钥仅存服务端；禁止未授权渗透与滥用
  • 因密钥泄露或对接不当造成的损失由商户自行承担
  • 危害平台安全的行为，平台有权限制接入、冻结账户并依法追责

1. 开通开发者权限

在商户控制台 → 开发者中开通 API 权限。

未开通时：

  • 网关所有接口返回 403（开发者权限未开通）
  • 控制台内 API 文档页也不会下发内容

2. 创建凭证并上传公钥

在控制台创建凭证，你会得到：

  • Access Key：以 ak_ 开头的公开标识，随每次请求发送
  • 商户 RSA 私钥：由你自己生成，只存在你的服务端，用于给请求加签
  • 把对应的商户 RSA 公钥上传到控制台，平台用它验签

私钥切勿外泄、切勿写进前端或提交到仓库。子账户不能使用开放网关凭证。

3. 配置 IP 白名单

在控制台把你调用服务器的出口公网 IP 加入白名单（支持 CIDR）。

  • 未配置白名单 → 所有请求拒绝
  • 不在白名单 → 返回 403（IP 不在白名单）

4. 选择环境地址（Base URL）

环境Base URL说明
沙箱 Sandboxhttps://uat-openapi.cafinx.com/v1联调、测试（推荐先走这里）
生产 Productionhttps://openapi.cafinx.com/v1正式业务

约定：

  • 接口路径均相对上述 Base URL，例如：GET https://uat-openapi.cafinx.com/v1/ping
  • 签名串里的 PATH 为不含域名的路径（如 /v1/ping），与请求 URI 一致
  • Webhook 回调地址是商户自己的域名（在控制台配置），不是上述 API 域名
  • 文档站：https://doc.cafinx.com
  • OpenAPI 规范：https://openapi.cafinx.com/v1/openapi.json（中文可加 ?locale=zh-CN）
  • 沙箱规范：https://uat-openapi.cafinx.com/v1/openapi.json
  • Postman：导入仓库 docs-sync/postman/cafinx-openapi.postman_collection.json，签名头用「认证与签名」页示例生成
  • 服务状态 / 工具下载：登录商户后台 → 开发者 → 工具与状态（OpenAPI / Postman / SDK 一键下载，见 服务状态）
  • 服务水平：见 服务水平（SLA）

5. 发起第一个请求

所有请求都要带 4 个签名头（见 认证与签名）。最简单的联调接口是 GET /ping：

export BASE_URL="https://uat-openapi.cafinx.com/v1"

# 实际请用 SDK 或「认证与签名」页的代码生成 X-Signature
curl "$BASE_URL/ping" \
  -H "X-Access-Key: ak_xxx" \
  -H "X-Timestamp: 1710000000000" \
  -H "X-Nonce: 3b1e...uuid" \
  -H "X-Signature: <Base64 RSA-SHA256 签名>"

成功返回统一信封：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userNo": "CFX-XXXX",
    "accessKey": "ak_xxx",
    "serverTime": 1710000000000,
    "message": "gateway ok"
  }
}

6. 推荐联调顺序

顺序接口说明
1GET /ping验签 + 网络
2GET /wallet查看 USD 余额
3GET /card-products可开卡 BIN（kind=standard 常规 / kind=shared 共享）
4POST /cards开卡（须 X-Idempotency-Key）
5POST /cards/{id}/recharge卡充值
6GET /transactions卡交易流水
7GET /wallet/flows钱包账变（含自动兑换 swap）

共享卡（额度池）

若产品目录中 kind=shared：

  1. POST /card-groups 建池（bin + authMoney）
  2. POST /card-groups/{id}/sub-cards 开附属卡
  3. POST /card-groups/{id}/recharge 池充值

详见 API 参考中的 共享卡 分组。

7. 资金模型（重要）

  • 消费（开卡费、卡充值等）只扣 USD 钱包
  • USD 不足时，系统按实时汇率自动把数字货币兑成 USD 补足（静默、同事务）
  • 自动兑换会写入 GET /wallet/flows 的 type=swap 流水
  • 资产仍不足 → 返回业务码 42201（余额不足）

无需单独调用「自动兑换」接口；也可以先走门户/App 的手动兑换。

8. 写接口与限流

  • 所有 POST 写接口必须带 X-Idempotency-Key（≤64 字符，建议业务单号）；24h 内同键同报文直接回放首次结果
  • 凭证默认 600 次/分钟；GET /cards/{id}/secure 另限 60 次/分钟
  • 假 Access Key / 假签名连打：同一 IP 约 20 次/分钟后直接返回 429（请求过于频繁）

9. 端到端示例（Node.js）

// 依赖：Node 18+（内置 crypto / fetch）。完整客户端见开发者 SDK 目录。
import crypto from 'crypto';
import fs from 'fs';

const BASE = 'https://uat-openapi.cafinx.com/v1';
const AK = 'ak_xxx';
const privateKey = fs.readFileSync('client_private_pkcs8.pem', 'utf8');

function sign(method, path, body = '') {
  const ts = String(Date.now());
  const nonce = crypto.randomUUID();
  const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('hex');
  const raw = `${method}\n${path}\n${ts}\n${nonce}\n${bodyHash}`;
  const signature = crypto.sign('RSA-SHA256', Buffer.from(raw), privateKey).toString('base64');
  return { ts, nonce, signature };
}

async function api(method, path, bodyObj) {
  const body = bodyObj ? JSON.stringify(bodyObj) : '';
  const fullPath = path.startsWith('/v1') ? path : `/v1${path.replace(/^\/v1/, '')}`;
  // 请求 URL 用 BASE + 资源路径；签名 PATH 与网关收到的一致，通常为 /v1/...
  const signPath = fullPath.startsWith('/v1') ? fullPath : `/v1${path}`;
  const resource = path.replace(/^\/v1/, '') || path;
  const { ts, nonce, signature } = sign(method, signPath.startsWith('/v1') ? signPath : `/v1${resource}`, body);
  const res = await fetch(`${BASE}${resource.startsWith('/') ? resource : '/' + resource}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Access-Key': AK,
      'X-Timestamp': ts,
      'X-Nonce': nonce,
      'X-Signature': signature,
      ...(method === 'POST' ? { 'X-Idempotency-Key': crypto.randomUUID() } : {}),
    },
    body: body || undefined,
  });
  return res.json();
}

// 1) 连通性
console.log(await api('GET', '/ping'));
// 2) 余额
console.log(await api('GET', '/wallet'));
// 3) 卡产品
console.log(await api('GET', '/card-products'));

生产将 BASE 换成 https://openapi.cafinx.com/v1。签名细节与 Java / Python / PHP / Go 示例见 认证与签名。

下一步

  • 认证与签名 —— 生成 X-Signature（含多语言示例）
  • 错误码 —— 网关 HTTP 状态 + 业务 code
  • Webhook —— 开卡 / 交易 / 3DS / 共享池等事件
  • 常见问题 FAQ —— 签名失败、401/403 排查
  • API 参考 —— 账户 / 卡产品 / 卡片 / 共享卡 / 交易 全量参数
    OpenAPI：在文档站 API Reference 查看，或请求 /v1/openapi.json

Updated about 2 months ago

Did this page help you?