变更记录
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、V1channelStatus、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。
