快速开始

API 文档 v1.6 · 更新于 2026-07-29
Base URL：沙箱 uat-openapi.cafinx.com · 生产 openapi.cafinx.com（路径均以 /v1 开头）

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

安全提示与免责声明

在接入前请务必阅读：

密钥与凭证：Access Key、商户 RSA 私钥仅允许存放在受控服务端；禁止写入前端、公开仓库、日志或截图。
防渗透与滥用：禁止对生产/沙箱进行未授权的渗透测试、漏洞扫描、爆破、重放或越权探测；合法安全评估须事先书面授权。
敏感数据：完整卡号 / CVV / 3DS OTP 禁止长期明文落库或落日志。
责任边界：因密钥泄露、凭证外传、配置错误、未授权测试或对接方操作不当导致的资金/数据损失，由商户自行承担；平台在法律允许范围内不承担责任。
平台处置权：凡危害 CAFINX 平台安全、稳定、声誉或合法权益的行为（包括但不限于攻击、渗透、滥用接口、盗用/买卖凭证、欺诈、洗钱风险、干扰服务或协助第三方实施上述行为），平台有权视情节采取限制/暂停/终止 API 接入、冻结相关资金或账户、列入黑名单、保留日志与证据、向监管或执法机关报告，并依法追究民事、行政或刑事责任；因此产生的损失由行为人自行承担，平台不予赔偿。
使用即确认：继续调用 API 或使用文档，即表示你已阅读并同意上述安全要求、免责条款与平台处置权。

1. 开通开发者权限

在商户控制台 → 开发者中开通 API 权限（管理端「商户权限」中的 API 接入 或历史字段 developer_enabled）。

未开通时：

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

2. 创建凭证并上传公钥

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

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

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

3. 配置 IP 白名单

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

未配置白名单 → 所有请求拒绝
不在白名单 → 403
本地联调请加入本机出口 IP（或经可信代理后的真实客户端 IP）

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

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

约定：

接口路径均相对上述 Base URL，例如沙箱联通性：GET https://uat-openapi.cafinx.com/v1/ping
签名串里的 PATH 为 不含域名 的路径（如 /v1/ping），与请求 URI 一致
Webhook 回调地址是商户自己的域名（在控制台配置），不是上述 openapi 域名
文档站：https://doc.cafinx.com

5. 发起第一个请求

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

# 沙箱示例（生产把 BASE_URL 换成 https://openapi.cafinx.com/v1）
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. 推荐联调顺序

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

共享卡（额度池）

若产品目录中 kind=shared：

POST /card-groups 建池（bin + authMoney）
POST /card-groups/{id}/sub-cards 开附属卡
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，不再查库

下一步

认证与签名 —— 必读，生成 X-Signature
错误码 —— 网关 HTTP 状态 + 业务 code
Webhook —— 开卡/交易/3DS/共享池等事件
API 参考 —— 账户 / 卡产品 / 卡片 / 共享卡 / 交易全量参数