文档

卡片

1. 基础地址

测试环境基础地址

https://api.futurepay-develop.com/api/v1/issuing/card

生产环境基础地址

https://api.futurepay.global/api/v1/issuing/card

1.1 接口一览

功能POST 路径成功时 data
创建卡片/create卡片对象
分页查询/paging分页对象，列表项为卡片对象
查询详情/{id}/detail卡片对象
查询完整卡号及 CVC/{id}/secret卡密对象
替换卡片/{id}/replace新卡片对象
激活卡片/{id}/activatetrue
冻结卡片/{id}/freezetrue
解冻卡片/{id}/unfreezetrue
注销卡片/{id}/canceltrue
查询消费控制/{id}/controls/detail消费控制对象
设置消费控制/{id}/controls保存后的消费控制对象

2. 统一响应

2.1 成功响应

{
  "code": "0",
  "msg": "succeeded",
  "serverTime": "1793923200000",
  "data": true,
  "success": true
}
字段说明
code响应码，成功为 0
msg响应说明
serverTime响应时间
data业务数据
success是否成功

2.2 失败响应

{
  "code": "CARD_NOT_FOUND",
  "msg": "Card not found",
  "serverTime": "1793923200000",
  "success": false
}

3. 创建卡片

POST /create
字段类型必填/默认说明
cardholderIdString必填持卡人编号
typeString默认 virtual虚拟卡
activeEnabledBoolean默认 true是否创建后立即激活
singleUseEnabledBoolean默认 falsefalse 为重复使用，true 为一次性使用
singleUseAmountNumber一次性卡必填一次性卡单笔消费金额上限，最小 0.01，整数最多 10 位，小数最多 2 位
validityHoursInteger默认 24一次性卡有效小时数，1–720

创建成功生成新的卡片 id。activeEnabled=true 时为 active，false 时为 inactive，之后可调用激活接口。

3.1 重复使用卡

{
  "cardholderId": "ich_example",
  "type": "virtual",
  "activeEnabled": true,
  "singleUseEnabled": false
}

3.2 一次性卡

{
  "cardholderId": "ich_example",
  "type": "virtual",
  "activeEnabled": false,
  "singleUseEnabled": true,
  "singleUseAmount": 100.00,
  "validityHours": 24
}

一次性卡创建时必须设置 singleUseAmount，首次交易清算后自动失效。

4. 分页查询

POST /paging
字段类型规则
idString选填，卡片业务编号精确筛选
cardholderIdString选填，持卡人业务编号筛选
statusString选填：active、inactive、frozen、controlled、canceled
typeString选填：virtual、physical
keywordString选填，系统卡编号、持卡人姓名关键词
cardNumberString选填，4 位尾号或 16 位完整卡号
startDateString选填，创建时间起始值
endDateString选填，创建时间结束值，不得早于 startDate
pageNumInteger默认 1，最小 1
pageSizeInteger默认 20，范围 1–100
{
  "pageNum": 1,
  "pageSize": 20,
  "status": "active",
  "type": "virtual"
}

响应 data：

{
  "pageNum": 1,
  "pageSize": 20,
  "total": 0,
  "totalPage": 0,
  "list": []
}

5. 卡片详情与卡片对象

POST /{id}/detail

请求体：

{}

卡片对象

{
  "id": "ic_example",
  "cardholderId": "ich_example",
  "type": "virtual",
  "currency": "USD",
  "status": "active",
  "last4": "4242",
  "expMonth": "11",
  "expYear": "2029",
  "singleUseEnabled": false,
  "singleUseExpiresAt": null,
  "createdAt": "2026-11-06 10:00:00",
  "updatedAt": "2026-11-06 10:00:00",
  "replacementFor": null
}
字段类型说明
idString卡片编号
cardholderIdString持卡人编号
typeStringvirtual 虚拟卡，physical 实体卡
currencyString币种
statusString见下表
last4String卡号末四位
expMonthString有效期月份
expYearString有效期年份
singleUseEnabledBoolean是否一次性卡
singleUseExpiresAtString一次性卡到期时间
createdAtString创建时间
updatedAtString更新时间
replacementForString被替换的旧卡编号
status含义新消费状态恢复方式
active已激活、使用中按消费控制规则处理—
inactive未激活不允许调用激活接口
frozen已冻结，临时停用不允许调用解冻接口
controlled风控管控中不允许由管理端解除管控，不能通过激活或解冻接口恢复
canceled已注销，永久停用不允许不可恢复

status 表示卡片当前状态；reason 用于提交注销或换卡的原因。换卡原因决定卡号等信息是否更换。

操作对卡号、CVV 和有效期的影响

CVV 为卡片安全码，对应接口字段 cvc；有效期对应 expMonth、expYear。

操作是否更换卡号是否更换 CVV是否更新有效期
激活、冻结、解冻否否否
注销（所有原因）否否否
设置消费控制否否否
到期换卡（expired）否是是
丢失、被盗换卡（lost、stolen）是是是

注销后原卡停止使用，不生成新的卡号或 CVV。一次性卡的 validityHours 调整其使用截止时间 singleUseExpiresAt。

6. 激活、冻结、解冻

操作POST 路径允许的当前状态成功后状态用途
激活/{id}/activateinactiveactive启用尚未激活的卡
冻结/{id}/freezeactivefrozen临时停用，之后可解冻
解冻/{id}/unfreezefrozenactive恢复已冻结的卡

上述三个接口均传：

{}

这三个操作不传 reason，保留原卡 id、cardholderId、卡号、CVC、有效期、消费限额、MCC 规则及已用额度。

7. 注销卡片

POST /{id}/cancel
字段类型规则
reasonString选填：lost、stolen、design_rejected、unactivated

7.1 注销原因

reason含义处理结果
lost卡片丢失注销卡片，标记丢失
stolen卡片被盗注销卡片，标记被盗
design_rejected卡片设计被拒绝注销卡片，记录设计拒绝原因
unactivated卡片未激活注销卡片，记录未激活原因
不传未指定原因注销卡片

不同原因的最终状态均为 canceled。注销不会自动创建替换卡。

7.2 状态与数据变化

项目注销后的结果
原状态active、inactive、frozen、controlled 均可申请注销
成功后状态canceled，不可再激活或解冻
卡片 id、cardholderId保持不变
卡号、CVC、有效期不换发，原卡停止新消费
历史交易保留，仍可查询

指定丢失原因：

{
  "reason": "lost"
}

不指定原因：

{}

8. 查询完整卡号与 CVC

POST /{id}/secret

请求体：

{}

响应 data：

{
  "id": "ic_example",
  "number": "4242424242424242",
  "cvc": "123",
  "expMonth": "11",
  "expYear": "2029"
}

9. 换卡

POST /{id}/replace
字段类型规则
reasonString必填：lost、stolen、expired
activateBoolean是否激活新卡，默认 true
{
  "reason": "lost",
  "activate": true
}

换卡成功返回新卡片对象。当前支持重复使用的虚拟卡；一次性卡、已注销卡不支持换卡。

9.1 换卡原因与卡密变化

  • 卡片到期（expired）：卡片已到期或即将到期。新卡保留原卡号，更新有效期并更换 CVV。
  • 卡片丢失（lost）：卡片遗失，需要停用旧卡。新卡使用新的卡号、CVV 和有效期。
  • 卡片被盗（stolen）：卡片被盗，需要停用旧卡。新卡使用新的卡号、CVV 和有效期。
换卡原因是否更换卡号是否更换 CVV是否更新有效期
到期（expired）否是是
丢失（lost）是是是
被盗（stolen）是是是

当前接口不支持卡片损坏（damaged）换卡。

9.2 新旧卡状态

activate新卡状态换卡成功后的旧卡状态
trueactive（已激活）canceled（已注销）
falseinactive（未激活）canceled（已注销）

以上状态适用于所有换卡原因。旧卡注销后不可恢复；新卡未激活时，可调用激活接口。

9.3 保留与变化的字段

项目换卡后的结果
卡片 id新卡生成新的编号；旧卡编号保留
cardholderId新旧卡相同，持卡人不变
replacementFor新卡指向旧卡编号
type、currency、singleUseEnabled沿用旧卡
卡号、CVC、有效期按换卡原因处理，见 9.1
消费限额、MCC 规则新卡继承旧卡配置
已用额度继承旧卡，换卡不会重置已用额度或重新开始额度周期
历史交易保留原记录，不改写为新卡编号

后续查询和操作新卡使用返回的新 id；activate=false 时，通过新卡 id 调用激活接口。

10. 消费控制

10.1 查询

POST /{id}/controls/detail

请求体：

{}

响应 data 示例：

{
  "limits": [
    {
      "amount": 5000.00,
      "currency": "USD",
      "interval": "monthly",
      "usedAmount": 100.00
    }
  ],
  "categories": [
    {
      "rule": "deny",
      "mcc": ["0742", "7311"]
    }
  ]
}

10.2 设置（全量替换）

POST /{id}/controls

设置成功更新消费限额和 MCC 规则，卡片状态、卡片 id、cardholderId、卡号及 CVC 保持不变。一次性卡传入 validityHours 时，同时调整其到期时间。

{
  "limits": [
    {
      "amount": 500.00,
      "interval": "per_authorization"
    },
    {
      "amount": 5000.00,
      "interval": "monthly"
    }
  ],
  "categories": [
    {
      "rule": "deny",
      "mcc": ["0742", "7311"]
    }
  ]
}
字段类型校验规则
limitsArray必填；一次性卡必须且只能有一条 per_authorization 单笔限额
limits[].amountNumber必填，最小 0.01，整数最多 10 位，小数最多 2 位
limits[].intervalString必填，见周期枚举；同一周期只能出现一次
categoriesArray必填，消费类别规则列表
categories[].ruleString必填，allow 白名单、deny 黑名单
categories[].mccArrayMCC 列表
validityHoursInteger选填，1–720，仅用于一次性卡有效期调整
interval含义
per_authorization单笔授权限额
daily每日限额
weekly每周限额
monthly每月限额
yearly每年限额
all_time累计限额

10.3 清空控制（重复使用卡）

{
  "limits": [],
  "categories": []
}

10.4 一次性卡控制

一次性卡每次设置或更新消费控制时，必须提交单笔消费金额上限；仅允许一条 per_authorization 限额，不能清空或改为其他周期。

{
  "limits": [
    {
      "amount": 500.00,
      "interval": "per_authorization"
    }
  ],
  "categories": [],
  "validityHours": 24
}

11. 常见错误

code含义
400必填、字段类型、格式或范围错误，具体原因见英文 msg
404API 路径不存在
VCC_PRODUCT_NOT_ENABLED商户未开通或未启用 VCC 产品能力
API_CARD_PARAMETER_INVALID参数组合不合法，例如周期重复或 MCC 不支持
API_CARD_PHYSICAL_NOT_SUPPORTED实体卡发卡/换卡暂未开放
API_CARD_SECRET_UNAVAILABLE卡密数据尚未准备好
CARD_NOT_FOUND卡片不存在或不属于当前商户
CARDHOLDER_NOT_FOUND持卡人不存在或不属于当前商户
CARDHOLDER_STATUS_INVALID持卡人当前不满足发卡条件
CARD_STATUS_INVALID当前卡片状态不允许执行该操作
CARD_ALREADY_ACTIVE已激活，不能重复激活
CARD_ALREADY_INACTIVE已冻结，不能重复冻结
CARD_ALREADY_CANCELED已注销
CARD_UNDER_CONTROL风控管控中
CARD_SINGLE_USE_LIMIT_REQUIRED一次性卡需要正确的单笔限额
CARD_SINGLE_USE_REPLACEMENT_NOT_ALLOWED一次性卡不支持换卡
CARD_LIMIT_CURRENCY_INVALID非 USD 卡片不支持设置美元限额
CARD_CONTROL_UPDATE_FAILED消费控制设置失败
CARD_ISSUE_FAILED发卡或换卡失败
VCC_ISSUING_PRODUCT_NOT_FOUND商户没有可用发卡产品或策略配置不满足要求

Updated about 17 hours ago

Did this page help you?