跳转到内容

变更记录 ​

2026-11-13 ​

  • 调整 V2 查询用户持卡概览:按共享资金账户 → 卡账户额度 → 产品 → 卡片嵌套;独立余额卡直接携带余额与额度查询结果。
  • 替换概览原顶层 sharedCardGroups、cardAccounts,概览额度不再重复返回取证卡号和账户标识;试用版概览调用方需要同步调整读取路径。
  • 余额/额度失败仍保留卡片、空金额不补零,旧卡列表、详情、余额及独立账户额度接口契约不变。

2026-11-10 ​

  • 新增 V2 查询用户持卡概览:GET /openapi/v2/cards/overview,全量返回已持卡记录、共享资金账户、独立卡余额及卡账户额度,说明账户关联和部分查询失败的处理方式。
  • 新增 V2 查询卡账户额度:GET /openapi/v2/cards/account-limits,说明额度字段、账户类型、可空金额,以及额度与资金余额的区别。
  • 同步中英文接口页、V2 索引和侧边栏。原卡列表、卡详情和余额接口保持原有契约。

2026-11-04 16:54 CST +0800 ​

  • 补充 V1/V2 查询 KYC 补件信息:GET /openapi/v1/users/kyc/supplement/context、GET /openapi/v2/users/kyc/supplement/context,说明补件资格、原资料和锁定字段。
  • 补件沿用原 KYC 提交接口,补齐必填参数 requestNo、originalRecordNo、expectedVersion、完整请求与响应示例,以及同一申请沿用费用、明确失败后重新申请的规则。

2026-10-30 10:00 CST +0800 ​

  • 新增万事达全球美元虚拟卡支持,保留原有万事达香港美元卡能力,并提供独立的 V2 接口路径和文档版本入口。

  • 提交 KYC 的 memberId 必填,校验当前租户下成员存在且与 email 一致;查询 KYC 状态仅需 email 和 cardTypeId。

  • 按卡产品明确 KYC 资料和开卡设备信息要求,支持证件永久有效。

  • 卡产品查询增加用户可申请信息;模拟交易增加可选商户场景字段。

  • 新增交易处理过程查询接口,展示授权、入账、撤销、关联退款和手续费等处理记录。

  • 新增卡片验证码接收邮箱修改接口:POST /openapi/v1/cards/{cardId}/3ds-contact/email、POST /openapi/v2/cards/{cardId}/3ds-contact/email。支持幂等提交;已受理不代表已生效,可通过 查询卡片验证码接收设置 查看脱敏联系方式及修改状态。

  • 新增卡片验证码接收手机修改接口:POST /openapi/v1/cards/{cardId}/3ds-contact/phone、POST /openapi/v2/cards/{cardId}/3ds-contact/phone。国际区号与手机号分别传入,支持幂等提交;已受理不代表已生效,可通过 查询卡片验证码接收设置 查看脱敏联系方式及修改状态。

  • 补齐 KYC submissionStatus、V1 channelStatus、NOT_SUBMITTED 和 V2 状态查询专属的 channelKycStatuses,区分总体与各渠道认证状态。

  • V1/V2 交易响应补充 accountPrincipalAmount、accountCurrency,区分原交易金额、账户本金与实际扣款。

2026-09-22 23:45 CST +0800 ​

  • 查询卡交易记录与消费 Webhook 统一金额口径:amount 为不含手续费的消费本金;新增 chargedAmount 表示包含本金及已收渠道、平台、租户手续费的实际扣款总额,扣款事实不足时为空。
  • totalFee 为平台与租户附加费用订单金额合计,不含渠道费,也不代表扣款成功;无附加费用订单时为零,订单金额缺失或币种无法归一时为空。不能用 amount + totalFee 代替实际扣款。
  • 手续费订单新增 chargeStatus,独立表达扣款结果;补充避免重复累计费用、USD/USDT 按 1:1 归一,以及 Webhook 事件快照与查询最新状态的区别。历史事件可能缺少 chargedAmount,缺失不能视为零。
  • 新增英文文档及对应页面的语言切换;首页按已保存的语言选择或浏览器语言偏好选择中英文。

2026-08-18 21:37 CST +0800 ​

  • 按沙箱 OpenAPI 5.6.1 同步当前 25 个接口的字段、枚举、约束和状态说明。
  • KYC 响应新增 subStatus 和 cardAccountId,并明确 annualIncome 的五个允许区间。
  • 卡余额响应补充 fpCardAccountId 及分账户、分资产余额结构;保留单资产兼容字段说明。
  • 修正用户、KYC、卡、交易、充值和激活状态值域,以及健康检查的字符串响应。

2026-08-05 12:20 CST +0800 ​

  • 查询卡交易记录响应使用 countryCode 返回消费国家或地区代码,并新增可空字段 merchantName 和 merchantCategoryCode。
  • 新增独立的商户 Webhook 接入文档,补充后台配置、签名、事件 Payload、eventNo 幂等、失败重试和历史事件兼容说明。

2026-08-04 19:44 CST +0800 ​

  • 商户 webhook Payload 升级为 schemaVersion: 2;eventType 仅表示 CARD_OPENING、CARD_RECHARGE、CARD_WITHDRAWAL、CARD_CONSUMPTION、CARD_MONTHLY 业务场景,具体结果由 status 表达。
  • 历史 PENDING/DEAD 事件重放保持原始请求体不变,接收方仍需兼容旧版状态型 eventType 和卡提现旧格式。

2026-08-03 19:13 CST +0800 ​

  • 商户 webhook Payload 新增稳定的 eventNo,明确采用至少一次投递语义;重试和人工重放保持相同的事件号与请求体。
  • 商户 webhook 请求新增 X-FP-Timestamp、X-FP-Api-Key、X-FP-Signature、X-FP-Body-Hash 平台签名 Header。

2026-08-03 18:30 CST +0800 ​

  • 创建卡激活申请接口响应新增 cardStatus,返回卡商激活结果中的实际卡状态。

2026-08-03 14:27 CST +0800 ​

  • 查询卡详情和查询用户卡列表接口明确卡状态取值为 pending-activation、active、locked、lost、inactive,并统一使用面向商户的状态说明。

2026-08-01 18:28 CST +0800 ​

  • 查询用户卡列表接口支持使用 email 或 memberId 二选一查询;使用 memberId 时仍返回该用户关联的全部卡列表。
  • 查询卡交易记录接口的每条交易响应新增 memberId,返回平台成员 ID。
  • 注册用户接口响应移除不再返回的 accountId 和 cardAccountId。

2026-08-01 14:27 CST +0800 ​

  • 卡详情、用户卡列表、用户开卡状态和绑卡接口的共享卡响应新增 memberId、dailyLimit、singleTransactionLimit、availableLimit、cardLimit 和 cardEmail;详情附加字段无数据时对应字段为空。
  • 卡状态说明修正为接口实际返回值,不再限定为固定状态枚举。

2026-08-01 11:42 CST +0800 ​

  • 卡详情、用户卡列表、用户开卡状态和绑卡接口的卡响应新增可空字段 cardTypeId。

2026-07-31 14:54 CST +0800 ​

  • 查询卡敏感信息接口响应移除无效的 algorithm、iv、authTag 和 ciphertext 字段,仅保留卡 ID、卡号、CVV 和有效期信息。

2026-07-31 14:47 CST +0800 ​

  • 查询用户开卡状态、查询卡详情和查询用户卡列表接口补充卡状态说明。

2026-07-30 18:38 CST +0800 ​

  • 卡敏感信息、余额、交易记录、锁定、解锁、重新激活、挂失和 PIN 修改接口统一使用 cardId,不再兼容旧请求参数 cardNo。
  • 创建卡激活申请接口的 cardId 必填和长度校验提示统一使用字段名 cardId。
  • 绑卡接口继续使用完整 cardNo 作为卡片校验凭据。

2026-07-29 15:36 CST +0800 ​

本次变更修正文档调用路径和公共说明:

  • 补全公共响应分页结构中的 pageSize 和 total。
  • 明确沙箱 Base URL、完整请求路径和签名 PATH 的关系,避免重复拼接 /openapi。
  • 明确健康检查接口仍需 OpenAPI 请求签名。
  • 清理单接口页残留的旧分组标题。

2026-07-28 11:45 CST +0800 ​

本次变更同步注册用户接口文档与当前代码:

  • POST /openapi/v1/users/createUser 请求参数补充必填字段 externalId。
  • POST /openapi/v1/users/createUser 响应字段将 externalUserId 修正为当前返回的 memberId。
  • GET /openapi/v1/users/list 请求参数和列表响应补充 externalId。

2026-07-27 17:37 CST +0800 ​

本次变更同步 OpenAPI 文档与当前接口:

  • 新增“分页查询当前租户用户”文档,路径为 GET /openapi/v1/users/list。
  • 在 OpenAPI 总览和侧边栏补充用户分页查询入口。
  • 移除“查询可办卡类型”响应中当前接口不再返回的筛选项、绑卡入口和排序/标签字段。
  • 补全“查询卡交易记录”响应中的 Provider 交易信息、商户地区和手续费订单字段。

2026-07-24 16:04 CST +0800 ​

本次变更补充 OpenAPI 文档中的状态字段说明:

  • 明确开卡订单、卡充值、卡提现等平台订单状态取值。
  • 明确卡状态、KYC 状态、卡激活状态和交易状态的取值说明。
  • 统一使用面向调用方的对外状态说明。

2026-07-24 14:27 CST +0800 ​

本次变更补充 OpenAPI 接入凭证生成和配置说明:

  • 新增 apiKey 与 merchantPrivateKey 的 OpenSSL 生成命令。
  • 明确商户需自行妥善管理 merchantPrivateKey。
  • 明确商户在 FuturePay 商户管理后台中的“Api 凭证”页面上新增 apiKey 后,系统会返回 futurePayPublicKey / FPAPIKey。

2026-07-23 17:54 CST +0800 ​

本次变更修正 OpenAPI 文档与接口代码不一致的内容:

  • 绑卡接口路径从 /openapi/v1/users/bindCard 修正为 /openapi/v1/cards/bindCard。
  • 绑卡接口移动到“卡接口”分组。
  • 绑卡请求参数补齐 expiryMonth、expiryYear、cvv。
  • 绑卡 cardNo 说明修正为最大 32 位,仅支持数字、空格和横线。
  • 创建卡激活申请请求字段从 cardNo 修正为 cardId。