VMCard Open API 技术 FAQ

文档说明

本文档汇总 VMCard Open API 接入及使用过程中常见的技术问题，包括费率与计费、鉴权与加密、Access Token、请求去重、卡片管理、交易查询、Webhook、Sandbox 与 Production 等内容，供 API 用户在开发、测试及生产环境接入时参考。

具体接口能力、卡产品及账户权限以 VMCard 后台实际配置和正式 API 文档为准。

1. 费率与计费口径

1.1 充值费

问：充值手续费是在资金充入 VM 主账户时收取，还是在调用 /rechargeCard 向储值卡充值时收取？

答：充值手续费在资金充入 VM 主账户时收取。调用 /rechargeCard 向储值卡充值不收取手续费。

问：如果账户入金和卡充值属于两个不同环节，是否会分别收费？

答：不会。卡充值环节不收取手续费。

问：计费基数、金额精度、舍入规则和最低手续费分别是什么？

答：手续费按照后台充值费率计算，结果保留至小数点后两位，不设最低手续费。

问：调用 /refundCard 将卡内余额退回账户时，已收取的充值手续费是否返还？

答：不返还。/refundCard 仅将卡内余额退回 VM 主账户，不涉及已收取的账户入金手续费返还。

1.2 开卡费

问：开卡费适用于哪些 product_code 或 BIN？

答：以商务后台卡片配置费率为准。

问：开卡失败是否收费？

答：不收费。

问：因重复请求被拦截时是否收费？

答：未实际创建卡片时不收取开卡费。

问：不同地区、卡组织和卡产品是否采用不同开卡价格？

答：是。具体以商务后台卡片配置费率为准。

1.3 其他费用

现行统一计费规则如下：

费用类型	计费规则
消费授权或失败交易费	卡组 `VC102/VC110/VC113`：0.20 USD/笔；卡组 `VC105`：0.30 USD/笔。
消费退款费	所有卡 BIN 均收取 10% 消费退款费，从总账扣除。
拒付或争议费	拒付（Declined Transaction）按交易失败处理，费用同消费授权或失败交易费；争议（Chargeback Transaction）按 35 USD/笔收取。
跨境交易费及外汇转换费	不收取。
卡余额退回费	不收取。
账户提现或资金转出费	VM 总账余额提现至外部钱包时，按提现金额的 4%+3 收取。

2. 鉴权与报文加密

2.1 实际请求格式

接入指南要求使用 VM 公钥加密业务参数，并按照以下格式发送：

{
  "content": "RSA密文"
}

问：Sandbox 和 Production 环境中，哪些接口必须使用 content 加密报文？

答：所有包含业务请求体的卡接口均必须使用 {"content":"RSA密文"} 格式，包括：

/createCard

/cardDetail

/freezeCard

/deleteCard

/rechargeCard

/refundCard

/cardTransaction

/updateCardLimit

/getCardList

/getCardFlow

/getProductCode 和 /getAccountBalance 不包含业务请求体，可以提交空 Body。

问：是否存在可以直接提交明文 JSON 的业务接口？

答：不存在。

问：成功响应中的 data 是否始终加密？

答：是。

问：参数、鉴权或解密失败时，错误响应是明文还是密文？

答：错误响应为明文。

问：是否可以提供 /getAccountBalance、/createCard、/cardDetail、/rechargeCard 和 /refundCard 的完整 Sandbox cURL 与实际响应示例？

答：相关示例已在 API 文档中提供。

2.2 RSA 长报文处理

问：RSA 4096 位密钥和 PKCS#1 v1.5 模式下，长报文如何处理？

答：

明文单块最大长度为 501 bytes。

密文单块长度为 512 bytes。

长报文按原文顺序逐块加密或解密，并按相同顺序拼接。

加密顺序：JSON UTF-8 bytes → RSA/PKCS#1 v1.5 加密 → Base64 编码 → Hex 编码。

解密顺序：Hex 解码 → Base64 解码 → RSA/PKCS#1 v1.5 解密 → UTF-8 JSON。

JSON 使用 json.dumps(data) 序列化后进行 UTF-8 编码。

解密后按照 UTF-8 字符串解析 JSON。

固定测试向量可按照 API 文档进行对接测试。

官方示例代码请参阅 API 文档中的 Python 示例。

2.3 VM 公钥与密钥轮换

问：VM 公钥的正式获取方式及指纹核验方式是什么？

答：通过 VMCard 指定的受控渠道获取。

问：VM 公钥更新时采用何种通知机制？

答：VM 公钥按需更新，并提前通知 API 用户。

问：API 用户公钥是否支持无中断轮换？

答：支持分钟级切换。

问：新旧 API 用户公钥是否可以在一段时间内并行生效？

答：不支持。

3. Access Token

/getAccessToken 当前使用 app_id 和 app_secret 获取 Token。

问题	答复
`Authorization` 请求头应直接填写 Token，还是使用 `Bearer <token>`？	直接填写 Token，不使用 Bearer 格式。
`expired_time` 是否为 Unix 秒时间戳？	是。
Token 默认有效期是多久？	7200 秒。
是否建议在到期前提前获取新 Token？	建议至少提前 600 秒获取。
获取新 Token 后应如何处理旧 Token？	获取新 Token 后建议立即切换使用最新 Token。
App Secret 和 Token 的撤销及轮换流程是什么？	如需进行 App Secret 或 Token 轮换，请联系 VMCard 技术支持。
是否支持通过 POST Body 或其他方式提交 `app_secret`？	不支持。`/getAccessToken` 当前为 GET 路由，通过 `app_id` 和 `app_secret` 参数获取。

4. 请求去重与最终结果查询

VMCard Open API 支持通过 X-Client-Request-Id 对请求进行去重控制。

4.1 Request ID 规则

X-Client-Request-Id 适用于全部 API，包括开卡、充值、余额退回、修改限额和删卡等接口。

规则如下：

最大长度为 64 个字符。

允许使用字母、数字以及 -、_、.、:。

唯一性按照 AppId + ClientRequestId 组合判断。

Request ID 当前永久保存。

相同 Request ID 无论参数是否相同，均返回 Duplicate Client Request Id。

重复请求不会返回首次请求的业务结果。

两个相同 Request ID 并发到达时，仅允许一个请求进入业务处理，其余请求返回 Duplicate Client Request Id。

Request ID 在请求通过鉴权和解密并进入 VM API 日志链路后生效。

4.2 Request ID 与业务结果

X-Client-Request-Id 用于请求去重，但当前不作为 Card Flow、Transaction 等最终业务数据的稳定关联字段。

Request ID 的登记与后续业务数据写入不属于同一个数据库事务，因此调用方不应仅依据 Request ID 判断业务最终结果。

当前没有统一的操作状态查询接口。

客户端未收到响应或执行结果不确定时，应根据具体业务查询最终状态：

开卡：/getCardList 或 /cardDetail

卡充值及余额退回：/getCardFlow

消费交易：/cardTransaction

对于涉及资金或卡片状态变化的写接口，如发生请求超时、网络中断或响应结果不明确，应先查询最终业务状态，再决定是否重新执行操作。

4.3 资金流水信息

对于卡充值及余额退回等资金操作，可通过 /getCardFlow 查询相关资金流水。

信息	当前情况
唯一操作流水号	`/getCardFlow` 返回 `flow_id`，可用于资金流水对账及去重。
操作状态	以 `/getCardFlow` 实际返回状态为准。
申请金额和实际金额	以相关接口实际返回字段为准。
手续费	当前不通过 `/getCardFlow` 单独返回手续费流水。
操作前后余额	当前返回该笔流水完成后的账户余额。
创建时间和更新时间	以相关接口实际返回字段为准。

5. 卡产品、卡类型与余额

5.1 产品信息

/getProductCode 当前返回：

BIN

产品码

卡类型

卡组织

发行地区

剩余可开卡数量

项目	当前规则
开卡费和充值费	`/getProductCode` 当前不返回费用字段。
`/createCard` 金额范围	`amount >= 1`；save 卡同时要求 `amount <= 50000`。
`/rechargeCard` 金额范围	`10 <= amount <= 50000`。
`/refundCard` 金额范围	`amount >= 0`。
3DS、AVS 和订阅支付能力	以后台产品详情为准。
支持或限制的国家、商户及 MCC	以 VMCard 商务通知及后台配置为准。
卡有效期及产品上下架	以后台实际产品状态及 VMCard 通知为准。

重要说明：当前 VMCard Open API 暂未开放 share / 额度卡产品。
以下涉及 share、wallet_balance 及 /updateCardLimit 的内容，仅用于说明现有接口字段和相关能力定义，不代表当前 API 用户可以实际开通或使用额度卡。
当前实际可用的卡产品及产品权限，以 VMCard 后台实际开放情况为准。

问：save 卡调用 /createCard 时，amount 是否代表首次卡充值金额？

答：是。

问：balance 与 wallet_balance 分别对应哪种资金池？

答：

balance：账户主余额，对应储值卡资金池。

wallet_balance：钱包余额，对应 share / 额度卡资金池。

当前暂未开放 share / 额度卡产品。

问：两个余额字段的币种是什么？

答：币种均为 USD，字段表示对应资金池的当前可用余额。

问：/updateCardLimit 修改 amount 时，实际如何影响额度钱包？

答：该接口设计用于 share 卡，传入的 amount 将作为新的总额度。

由于当前暂未开放 share / 额度卡产品，该接口对应能力目前不对 API 用户开放使用。

5.3 地址与持卡人字段

问：/createCard 中的 card_address 是否可以完全省略？

答：可以。

问：传入 card_address 后，address_line_two 是否必填？

答：非必填，无内容时可以传空字符串。

问：姓名、国家、州、邮编、区号、手机号和邮箱有哪些格式要求？

答：

first_name 和 last_name 必填，且不得为空。

card_address 整体可选。

如传入 card_address，除 address_line_two 外，其余内部字段均为必填。

地址字段仅支持字母、数字、空格和连字符（-）。

地址字段不支持中文或逗号、句号、#、@ 等特殊符号。

区号、手机号和邮箱均为可选字段，当前无额外格式限制。

5.4 消费限额

问：当前卡片的单笔及单日消费限额是多少？

答：

单笔消费限额：10,000 USD。

单日交易限额：100,000 USD。

6. 储值卡充值与余额退回

问：/rechargeCard 和 /refundCard 的资金分别从哪里扣除、退回哪里？

答：

/rechargeCard：从主账户 balance 扣款，并增加储值卡余额。

/refundCard：从储值卡余额退回主账户 balance。

问：是否支持部分充值和部分余额退回？

答：支持按照指定 amount 进行充值或余额退回。

/rechargeCard 当前金额范围：

10 <= amount <= 50000

/refundCard 当前金额规则：

amount >= 0

问：充值和余额退回是同步完成，还是可能进入 PENDING？

答：接口当前采用同步处理。

问：接口返回字符串 "true" 时代表什么？

答："true" 表示该接口当前同步处理成功。

实际卡余额及账户余额应以 /cardDetail、/getCardFlow 等查询接口返回的数据为准。

问：资金操作是否可以查询 flow_id？

答：可以。相关资金流水可以通过 /getCardFlow 查询，每笔资金流水包含唯一的 flow_id。

问：卡片存在待清算授权时，最大可退余额如何计算？

答：/refundCard 的可退金额以卡片当前可用余额为准。

待清算授权对应的金额通常已经被卡组织或通道冻结或占用，因此通道返回的可用余额会相应减少，VM API 不会再次重复扣减该部分金额。

问：/getCardFlow 中的主要字段分别表示什么？

答：

flow_id：资金流水 ID。

amount：流水金额。

reality_amount：实际处理金额。

account_balance：该笔流水完成后的账户余额。

ref、code：资金流水对应的扩展字段。

问：getCardFlow.flow_id 是否全局唯一且不会复用？

答：是。

问：卡资金流水是否包含手续费及其币种？

答：当前 /getCardFlow 不包含独立手续费流水，也不返回手续费币种字段。

7. 交易记录与对账

7.1 交易关联

问：auth_id 是否可以贯穿 Authorization、Settlement、Reversal 和 Refund？

答：不能保证。

当前对外返回的 auth_id 是 VMCard 系统生成的交易记录 ID，可以用于标识单条返回记录，但不能稳定作为 Authorization、Settlement、Reversal 和 Refund 整个交易生命周期的统一关联 ID。

问：每条交易事件是否具有独立且不可变的事件 ID？

答：当前没有独立的统一事件 ID。

问：一次授权是否可能发生部分清算或多次清算？

答：可以。

问：一次消费是否可能发生部分退款或多次退款？

答：可以。

问：当前是否提供 ARN、RRN、STAN 或其他网络参考号？

答：暂不提供。

7.2 查询与分页

针对 /cardTransaction，当前规则如下：

项目	答复
`start_time` 和 `end_time` 的筛选字段	按 `auth_time` 筛选。
时间范围边界	包含起止时间。
时间字段时区	`auth_time` 的存储时区取决于各通道返回的数据时区。
默认排序	按 `auth_time` 降序。
分页稳定性	当前采用 offset/limit 分页，查询期间存在新增记录时不能保证分页结果完全稳定。
最大查询跨度及数据保留期	`page_size` 最大为 1000；当前未限制查询时间跨度，历史数据目前长期保留。
增量查询	当前不支持按更新时间、游标或独立事件 ID 进行增量查询。

7.3 金额、币种与精度

问：auth_amount / auth_currency 与 settle_amount / settle_currency 分别表示什么？

答：

auth_amount：授权金额。

auth_currency：授权币种。

settle_amount：清算金额。

settle_currency：清算币种。

对外返回的金额均以绝对值表示。

问：退款和授权撤销金额采用正数还是负数？

答：采用正数。

调用方应根据交易 type 判断资金方向，不应根据金额正负判断交易类型。

问：金额支持的小数位和舍入规则是什么？

答：

接口不限制输入金额的小数位数。

业务处理及存储统一保留两位小数。

使用四舍五入规则。

1.234 处理为 1.23。

1.235 处理为 1.24。

建议调用方提交金额时直接保留两位小数。

问：如何获取财务明细或交易全量导出？

答：可以通过 VMCard 后台导出财务明细。

如有其他对账需求，请联系 VMCard 技术支持。

8. Webhook 与 3DS 通知

8.1 Webhook 来源与安全验证

当前普通交易 Webhook 和 3DS 通知支持情况如下：

验证能力	当前情况
HMAC 或公钥签名	暂不支持。
Callback Secret	当前仅配置回调 URL，不提供独立 Callback Secret。
`timestamp + nonce` 防重放机制	暂不支持。
独立 `event_id` 或 `delivery_id`	暂不提供。
mTLS	当前未使用。
Production 固定出口 IP	`8.219.3.65`。

Production Webhook 出口 IP 如发生调整，VMCard 将提前通知 API 用户进行配置更新。

8.2 Webhook 成功响应

Webhook 接收端建议返回：

HTTP 200 OK

交易流水类 Webhook 同时应返回：

{
  "msg": "ok"
}

以下情况可能被视为投递失败：

HTTP 状态码为非 2xx。

网络连接失败。

请求超时。

交易流水类 Webhook 返回的 msg 不为 ok。

响应格式不符合当前成功判定规则。

8.3 Webhook 投递与重试

交易流水类 Webhook 当前规则：

请求超时时间为 30 秒。

当前最多总计尝试 3 次。

HTTP 4xx / 5xx、网络异常、连接异常、请求超时或响应格式不符合成功要求时，会被视为投递失败。

当前未配置固定重试间隔。

实际重试时间受队列调度和 Worker 负载影响。

不保证固定重试间隔或严格的最长投递时间。

不保证 Webhook 严格按照交易发生顺序投递。

调用方应能够处理重复通知。

VM API 其他异步回调类请求：

请求超时时间为 30 秒。

当前队列配置可能与交易流水类 Webhook 不同。

具体投递规则以对应接口说明为准。

8.4 3DS

项目	当前情况
`challenge_id` 或 `transaction_id`	当前回调不包含。
独立事件 ID	当前不提供。
OTP 生成时间和到期时间	回调中不返回。
通知次数或尝试次数	Payload 中不包含。
OTP 重放防护字段	当前不提供。
Webhook 查询或人工补发接口	当前不提供。

当前 VMCard 系统所有已开放卡 BIN 默认关闭 3DS 功能，因此现阶段不会产生 3DS 通知。
如果后续相关产品开放 3DS 能力，VMCard 将提前通知 API 用户。

9. 成功码、错误码与限流

9.1 成功判断

问：如何判断 VMCard API 请求是否成功？

答：

code = 0

表示业务请求成功。

code != 0

表示业务请求失败。

具体错误原因应结合接口返回的 code 和错误信息判断。

9.2 常见错误码

问：Token 无效、Token 过期和 App Secret 错误分别对应什么错误码？

答：

Authorization 为空、Token 无效或 Token 已过期：400003

App Secret 错误：400007

问：400004 与 400007 分别表示什么？

答：

400004：未开通权限（No Permission）

400007：App Secret 错误

9.3 重试原则

问：哪些错误通常可以确认请求尚未进入业务处理？

答：例如：

Authorization Is Empty

Invalid Token

Invalid AppId

Params Content Error

请求解密失败

对于开卡、充值、余额退回、删卡等写操作，如果发生网络超时、卡服务异常或客户端未收到响应，不建议直接重复提交。

应先通过对应查询接口确认最终业务结果。

9.4 限流规则

Sandbox 与 Production 当前限流规则一致：

同一接口在同一主体下最多调用 100 次/分钟。

同一接口在同一主体下最多调用 86400 次/24 小时。

分钟限流采用最近 60 秒滑动窗口。

日限流采用最近 24 小时滑动窗口。

最大并发连接数为 1000。

触发限流时当前不返回 Retry-After。

业务 API 按以下维度限流：

AppId + API Endpoint

/getAccessToken 按以下维度限流：

来源 IP + 请求 URL

10. 冻结、删除与未完成交易

10.1 卡片状态

问：VMCard 卡片状态分别代表什么？

答：

ACTIVE：卡片处于激活状态。

CANCELLED：卡片被冻结或停用，可以重新提交 ACTIVE 恢复。

DELETED：卡片已经删除，不可恢复。

VMCard 风控主动关闭卡片时使用 DELETED。

因 CVV 或有效期连续输入错误导致发卡行冻结时，卡片可能表现为 CANCELLED，一般等待 3 至 5 天后自动解除。

10.2 冻结后的交易

问：冻结卡片后是否还可能发生 Settlement、Refund 或 Reversal？

答：可能。

冻结或删除卡片只能阻止新的 Authorization。

对于冻结或删除前已经批准，并且尚未完成清算或全额撤销的 Authorization，商户后续仍可能提交 Settlement。

Refund 和 Reversal 也可能在卡片冻结后继续发生。

10.3 迟到 Settlement

问：迟到 Settlement 如何扣款？

答：

迟到 Settlement 优先从卡内余额扣除。

如果卡内余额不足，则从主账户总账扣除。

账户总账余额不足时，控制台可能显示负数。

10.4 删除卡片

问：/deleteCard 是否不可逆？

答：是。

卡片进入 DELETED 状态后不可恢复。

问：卡内有余额或存在待清算 Authorization 时是否允许删除？

答：允许。

删除卡片时，系统会先执行卡余额退回，再执行删除操作。

卡余额自动退回与删卡属于同一事务。

如果自动退回失败，删除操作整体失败，卡片保持原状态。

问：删除卡片后发生商户退款时，资金进入哪里？

答：

卡片仍处于激活状态：退款进入卡内。

卡片已经删除：退款进入账户总账。

问：删除卡片后是否仍可能发生迟到 Settlement？

答：可能。

对于删除前已经批准，且尚未完成清算或全额撤销的 Authorization，商户仍可能在后续提交 Settlement。

因此调用方不应将“卡片已经删除”理解为所有历史授权交易均已经终止。

11. Sandbox 与 Production

VMCard Open API 当前提供两个环境：

Sandbox

Production

当前不提供独立 UAT 环境。

Sandbox 用于 API 集成开发及 Production 上线前测试。

Sandbox 与 Production 的业务请求加密格式一致。

所有包含业务请求体的卡接口必须提交：

{
  "content": "RSA密文"
}

适用接口包括：

/createCard

/cardDetail

/freezeCard

/deleteCard

/rechargeCard

/refundCard

/cardTransaction

/updateCardLimit

/getCardList

/getCardFlow

/getProductCode 和 /getAccountBalance 不包含业务请求体，可以提交空 Body。

业务接口不支持直接提交明文 JSON。

成功响应中的 data 为加密数据。

参数、鉴权或解密失败时，错误响应为明文。

RSA 规则如下：

密钥长度：4096 位。

填充方式：PKCS#1 v1.5。

明文单块最大长度：501 bytes。

密文单块长度：512 bytes。

长报文按照原文顺序逐块加密或解密，并按顺序拼接。

加密顺序：JSON UTF-8 bytes → RSA 加密 → Base64 编码 → Hex 编码。

解密顺序：Hex 解码 → Base64 解码 → RSA 解密 → UTF-8 JSON。

JSON 使用 json.dumps(data) 序列化后进行 UTF-8 编码。

12. 时间字段

问：/cardTransaction.auth_time 是否包含 Timezone 或 UTC Offset？

答：当前不包含 Timezone 或 UTC Offset 字段。

auth_time 来自各通道交易处理后的入库时间，其时区可能因通道而异。

调用方如需统一时区进行内部对账，应在业务侧根据自身对账规则进行标准化处理。

13. 交易关联字段

问：当前是否提供供应商父交易 ID、Settlement / Refund 父子字段或其他稳定的交易关联键？

答：当前暂不提供。

现有对外字段无法保证将 Authorization、Settlement、Reversal 和 Refund 稳定关联为完整交易生命周期。

14. `/refundCard` 最低保留余额

本章节仅适用于当前已开放的 save / 储值卡产品。
当前 VMCard 暂未开放 share / 额度卡产品。

不同储值卡产品调用 /refundCard 时的最低保留余额如下：

产品	卡组织及发卡国家	BIN	最低保留余额
VC110	Visa，美国	`43612077`、`43612078`、`43612079`、`43612080`、`43612081`、`40041641`、`40024200`	0.10 USD
VC113	Mastercard，美国	`537872`	0.10 USD
VC102	Mastercard，美国	`555671`、`544015`、`525962`	可退至 0.00 USD

Sandbox 与 Production 当前采用相同规则。

调用 /refundCard 时，应确保退回后的卡余额满足对应产品的最低保留余额要求。

15. Hosted Reveal 与卡数据展示

问：VMCard 是否提供 Hosted Reveal、iframe、一次性展示 Token 或其他托管式卡数据揭示能力？

答：当前暂不提供以下能力：

VMCard 托管的完整卡数据展示页面。

可嵌入的 iframe。

一次性或短时有效的卡数据展示 Token。

一次性或短时有效的卡数据展示链接。

其他由 VMCard 托管的完整卡数据揭示方式。

16. 商户退款的数据通道及交易类型

问：商户主动发起的退款会通过哪个接口返回？

答：

商户主动退款主要通过 /cardTransaction 返回。

同一笔商户退款不会同时作为 /getCardFlow 资金流水返回。

各类型含义如下：

/getCardFlow 中 type = "card recharge"：平台账户资金转入卡片。

/getCardFlow 中 type = "card refund"：卡内余额退回平台账户。

/cardTransaction 中 type = "Refund"：商户消费退款。

/cardTransaction 中 type = "Reversal"：消费授权撤销。

17. 商户退款关联及金额语义

问：退款记录如何关联原始消费？

答：当前只能确认退款记录与原消费属于同一张卡。

现有对外字段无法稳定将退款记录关联至某一笔具体原始消费。

问：退款金额是正数还是负数？

答：以正数返回。

调用方应根据交易 type 判断资金方向，不应根据金额正负判断。

问：如何判断商户退款已经完成？

答：应同时满足：

type = "Refund"
status = "COMPLETE"

18. Webhook 商户退款通知

配置交易 Webhook 后，已经落库并触发转发的商户退款记录会通过同一 Webhook 地址异步通知。

退款事件类型为：

type = "Refund"

Webhook Payload 字段如下：

参数名	类型	说明
`auth_id`	String	交易 ID
`card_id`	String	卡 ID
`vm_card_id`	String	VM 卡 ID
`auth_time`	String	交易授权时间
`auth_amount`	Double	授权金额
`auth_currency`	String	授权币种
`settle_amount`	Double	清算金额
`settle_currency`	String	清算币种
`status`	String	交易状态
`type`	String	交易类型
`merchant_name`	String	交易商户
`create_time`	String	创建时间
`description`	String	交易详情或交易失败信息

19. Sandbox 商户退款测试

问：Sandbox 环境如何模拟商户退款？

答：VMCard Open API 当前不提供独立的商户退款模拟接口。

如需开展商户退款相关联调测试，请联系 VMCard 技术支持。

FAQ

VMCard Open API 技术 FAQ#

文档说明#

1. 费率与计费口径#

1.1 充值费#

1.2 开卡费#

1.3 其他费用#

2. 鉴权与报文加密#

2.1 实际请求格式#

2.2 RSA 长报文处理#

2.3 VM 公钥与密钥轮换#

3. Access Token#

4. 请求去重与最终结果查询#

4.1 Request ID 规则#

4.2 Request ID 与业务结果#

4.3 资金流水信息#

5. 卡产品、卡类型与余额#

5.1 产品信息#

5.2 save 与 share#

5.3 地址与持卡人字段#

5.4 消费限额#

6. 储值卡充值与余额退回#

7. 交易记录与对账#

7.1 交易关联#

7.2 查询与分页#

7.3 金额、币种与精度#

8. Webhook 与 3DS 通知#

8.1 Webhook 来源与安全验证#

8.2 Webhook 成功响应#

8.3 Webhook 投递与重试#

8.4 3DS#

9. 成功码、错误码与限流#

9.1 成功判断#

9.2 常见错误码#

9.3 重试原则#

9.4 限流规则#

10. 冻结、删除与未完成交易#

10.1 卡片状态#

10.2 冻结后的交易#

10.3 迟到 Settlement#

10.4 删除卡片#

11. Sandbox 与 Production#

12. 时间字段#

13. 交易关联字段#

14. /refundCard 最低保留余额#

15. Hosted Reveal 与卡数据展示#

16. 商户退款的数据通道及交易类型#

17. 商户退款关联及金额语义#

18. Webhook 商户退款通知#

19. Sandbox 商户退款测试#

VMCard Open API 技术 FAQ

文档说明

1. 费率与计费口径

1.1 充值费

1.2 开卡费

1.3 其他费用

2. 鉴权与报文加密

2.1 实际请求格式

2.2 RSA 长报文处理

2.3 VM 公钥与密钥轮换

3. Access Token

4. 请求去重与最终结果查询

4.1 Request ID 规则

4.2 Request ID 与业务结果

4.3 资金流水信息

5. 卡产品、卡类型与余额

5.1 产品信息

5.2 save 与 share

5.3 地址与持卡人字段

5.4 消费限额

6. 储值卡充值与余额退回

7. 交易记录与对账

7.1 交易关联

7.2 查询与分页

7.3 金额、币种与精度

8. Webhook 与 3DS 通知

8.1 Webhook 来源与安全验证

8.2 Webhook 成功响应

8.3 Webhook 投递与重试

8.4 3DS

9. 成功码、错误码与限流

9.1 成功判断

9.2 常见错误码

9.3 重试原则

9.4 限流规则

10. 冻结、删除与未完成交易

10.1 卡片状态

10.2 冻结后的交易

10.3 迟到 Settlement

10.4 删除卡片

11. Sandbox 与 Production

12. 时间字段

13. 交易关联字段

14. `/refundCard` 最低保留余额

15. Hosted Reveal 与卡数据展示

16. 商户退款的数据通道及交易类型

17. 商户退款关联及金额语义

18. Webhook 商户退款通知

19. Sandbox 商户退款测试