VM Open API 技术问答与确认记录

文档说明

本文档汇总 VM Open API 对接过程中的问题与书面答复。为确保沟通记录完整，主 QA 与后续各日期的补充确认均按原有时间顺序保留。

1. 费率与计费口径

1.1 充值费

目前沟通的充值费率为 0.3%，请确认以下事项。

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

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

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

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

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

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

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

答：卡充值本身不收取手续费，因此不存在该部分手续费返还。

1.2 开卡费

目前沟通的开卡费为每张 0.30 USD，请确认以下事项。

问：该价格适用于哪些 product_code 或 BIN？

答：适用于以下 BIN：537872、555671、544015、525962。

问：开卡失败是否收费？

答：不收费。

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

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

问：不同地区、卡组织、储值卡和额度卡是否采用不同价格？

答：是。如费率发生变动，将另行通知。现阶段以本节第一项所列 BIN 及价格为准。

1.3 其他费用

在拒付率（Declined Transaction Rate）处于正常范围时，以下费用均予以豁免。现行计费规则如下。

费用类型	计费规则
消费授权或失败交易费	BIN `537872`：0.20 USD/笔；BIN `555671`、`544015`、`525962`：0.30 USD/笔。
消费退款费	BIN `537872`：每笔消费退款收取 5% 手续费；BIN `555671`、`544015`、`525962`：每笔消费退款收取 10% 手续费。
拒付或争议费	拒付（Declined Transaction）按交易失败处理，费用同消费授权或失败交易费；争议（Chargeback Transaction）按 35 USD/笔收取。
跨境交易费及外汇转换费	不收取。
卡余额退回费	不收取。
账户提现或资金转出费	VM 总账余额提现至外部钱包时，按提现金额的 2% 收取。

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 编码 → 对 Base64 字符串进行 Hex 编码。

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

JSON 使用 json.dumps(data) 序列化后进行 UTF-8 编码；解密后按 UTF-8 字符串解析 JSON。

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

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

2.3 VM 公钥与密钥轮换

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

答：通过单独的受控渠道沟通。

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

答：按需更新并通知。

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

答：支持分钟级切换。

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

答：不支持。

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 同时存在？	建议仅使用最新 Token。
App Secret 和 Token 的撤销及轮换流程是什么？	请参阅后续相关问题的答复。
是否支持通过 POST Body 或其他方式提交 `app_secret`？	不支持。`/getAccessToken` 当前为 GET 路由，通过 `app_id` 和 `app_secret` 参数获取。

4. 请求幂等与最终结果查询

2026-06-09 变更日志中新增了 X-Client-Request-Id。

问：该请求头是否适用于全部 API，特别是 /createCard、/rechargeCard、/refundCard、/updateCardLimit 和 /deleteCard？

答：是。

问：Request ID 的长度、字符集和唯一性作用域是什么？

答：长度不得超过 64 个字符，允许使用字母、数字以及 -、_、.、:。唯一性按照 AppId + ClientRequestId 组合判断。当前实现仅记录格式无效标记，不会直接拦截格式不合规的请求。

问：Request ID 在服务端保存多久？

答：目前永久保存。

问：使用相同 Request ID 和相同参数再次提交时，是否返回原请求结果？

答：不会返回原请求结果，而是返回 Duplicate Client Request Id。

问：相同 Request ID 但参数不同时如何处理？

答：仍按重复 Request ID 拦截，并返回 Duplicate Client Request Id。

问：两个相同 Request ID 并发到达时如何处理？

答：仅允许一个请求进入业务处理，其余请求返回 Duplicate Client Request Id。

问：首次请求已经执行成功，但客户端未收到响应时，应如何查询最终结果？

答：目前没有统一的操作状态查询接口，应按业务结果分别查询：

开卡结果：/getCardList 或 /cardDetail

充值及卡余额退回结果：/getCardFlow

消费交易结果：/cardTransaction

对于涉及开卡或资金变动的写接口，当前可获得或查询的信息如下：

信息	当前口径
唯一操作流水号	`/getCardFlow` 返回 `flow_id`，可用于对账和去重。
操作状态	需结合具体业务判断。
申请金额和实际金额	需结合具体业务判断。
手续费	暂无统一返回。
操作前后余额	当前返回操作后的余额。
创建时间和更新时间	以相关接口实际返回字段为准。

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

5.1 产品信息

/getProductCode 当前返回 BIN、产品码、卡类型、卡组织、发行地区及剩余可开卡数量。

项目	当前口径
开卡费和充值费	接口不返回。
`/createCard` 金额范围	`amount >= 1`；save 卡同时要求 `amount <= 50000`。
`/rechargeCard` 金额范围	`10 <= amount <= 50000`。
`/refundCard` 金额范围	`amount >= 0`。具体最低保留余额请参阅 2026-08-15 的补充确认。
单卡、单日和账户级频次限制	线下沟通。
3DS、AVS 和订阅支付能力	单独沟通。
支持或限制的国家、商户及 MCC	单独沟通。
卡有效期及产品上下架通知	单独沟通。

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

答：是。

问：share 卡的 amount 是否代表总额度？

答：是。

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

答：balance 为账户主余额，对应储值卡资金池；wallet_balance 为钱包余额，对应共享卡/额度卡资金池。

问：两个余额字段的币种是什么，是否均为可用余额？

答：币种均为 USD，且均表示可用余额。

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

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

问：降低后的额度小于已使用金额或待清算授权时，接口如何处理？

答：系统不会判断待清算授权。满足接口条件时即可调整，但调整后可能导致交易失败。

5.3 地址与持卡人字段

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

答：可以。

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

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

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

答：

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

card_address 整体可选；如传入，则除 address_line_two 外，其余内部字段均为必填。

地址字段仅支持字母、数字、空格和连字符（-），不支持中文或逗号、句号、#、@ 等特殊符号。

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

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

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

答：/rechargeCard 从主账户 balance 扣款并增加储值卡余额；/refundCard 从储值卡余额退回主账户 balance。

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

答：支持按指定 amount 充值或退回。/rechargeCard 金额范围为 10 至 50000；/refundCard 要求 amount >= 0。

问：单笔和单日金额上下限是多少？

答：需单独沟通确认。

问：处理是同步完成，还是可能进入 PENDING？

答：同步完成。

问：接口返回字符串 "true" 时，是否代表资金已经最终完成？

答：是。最终仍应以卡详情、卡流水及资金流水的查询结果为准。

问：是否可以返回 flow_id 或其他资金操作流水号？

答：相关口径见前文 /getCardFlow 的说明。

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

答：/refundCard 的可退金额以卡片当前可用余额为准。待清算授权对应的金额通常已被卡组织或通道冻结、占用，通道返回的可用余额会相应减少；VM API 不会再次重复扣减该部分金额。

问：getCardFlow 中的 amount、reality_amount、account_balance、ref 和 code 分别表示什么？

答：

flow_id：资金流水 ID。

amount：流水金额。

reality_amount：实际金额字段。

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

ref、code：透传资金流水表中的对应字段。

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

答：是。

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

答：不包含手续费流水，也不返回手续费币种字段。

7. 交易记录与对账

7.1 交易关联

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

答：当前对外返回的 auth_id 是 VM 系统生成的交易记录 ID，并非通道原始授权 ID。该字段可以标识一条返回记录，但不能稳定作为 Authorization、Settlement、Reversal 和 Refund 之间的统一关联 ID。

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

答：没有。

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

答：可以。

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

答：可以。

问：清算、撤销和退款分别通过哪个字段关联原始授权或清算记录？

答：早期答复为通过 auth_id 关联。经后续确认，auth_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 分别表示清算金额和清算币种。对外返回的金额取绝对值。

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

答：采用正数。

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

答：

接口不限制输入的小数位数，但业务处理及存储统一保留两位小数。

使用四舍五入规则，例如 1.234 处理为 1.23，1.235 处理为 1.24。

建议调用方传入金额时保留两位小数，超出部分将自动舍入。

问：如何获取日结账单、余额快照或交易全量导出？

答：可通过后台导出财务明细。如有其他需求，可在对接群组中反馈。

8. Webhook 与 3DS 通知

8.1 来源验证

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

验证能力	当前情况
HMAC 或公钥签名	暂不支持。
可配置的回调 Secret	当前仅配置回调 URL，不提供独立的 Callback Secret。
`timestamp` 与 `nonce`	交易数据中包含交易时间，但该字段不是用于验签或防重放的 `timestamp + nonce`。
唯一 `event_id` 或 `delivery_id`	普通交易可使用 `auth_id` 识别交易，但没有独立的 `event_id` 或 `delivery_id`；3DS 通知也没有独立事件 ID。
固定出口 IP 清单	需单独沟通确认。
mTLS	当前回调未使用双向 TLS。

8.2 字段与投递规则

问题	答复
普通 Webhook 中卡 ID 的正式字段名是 `cardId` 还是 `card_id`？	`card_id`。
Webhook 接收成功是否仅判断 HTTP 2xx？	早期口径为判断 HTTP Code，不强制校验 Message，但建议返回成功消息。后续不同类别的 ACK 规则有所细化。
响应超时时间	30 秒。
“重复发送三次”的含义	最多总计尝试 3 次。后续答复对不同 Webhook 类别作了区分。
重试间隔和最长投递时间	早期口径为超时后重试。后续确认未承诺固定重试间隔或严格最长投递期。
是否可能重复或乱序投递	不保证严格有序，业务系统不得假设通知有序或仅投递一次。
是否提供投递日志、失败查询及人工补发	需单独沟通，后续答复对不同 Webhook 类别作了说明。

8.3 3DS

项目	当前情况
`challenge_id` 或 `transaction_id`	当前 3DS 回调不包含这两个字段。
唯一事件 ID	不提供独立的 `event_id` 或 `delivery_id`。
OTP 生成时间和到期时间	回调中不返回。
同一交易的通知次数或尝试次数	Payload 不包含通知次数或尝试次数；系统队列失败时会进行重试。
OTP 重放防护规则	当前未提供重放防护字段或规则。
Webhook 遗漏后的查询或补发方式	当前没有 3DS 通知查询或补发接口；失败时由系统队列自动重试。

备注：现阶段 VMCardio 系统所有卡 BIN 默认关闭 3DS 功能，因此不会发送 3DS 通知。如该配置后续发生变化，将提前通知。

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

问：所有接口的统一成功判断规则及 HTTP 状态码与业务 code 的对应关系是什么？

答：原始答复中未形成覆盖所有接口的完整映射。现有明确口径为：调用 VM API 时，响应体 code = 0 表示业务请求成功，非 0 表示失败。各接口仍应以正式接口文档和实际响应为准。

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

答：Authorization 为空、Token 无效或过期时返回 400003；App Secret 错误时返回 400007。

问：400004 与 400007 分别对应哪种权限问题？

答：400004 表示未开通权限（No Permission）；400007 表示 App Secret 错误。

问：哪些错误可以确认请求未执行并安全重试？

答：例如 Authorization Is Empty、Invalid Token、Invalid AppId、Params Content Error 及解密失败等。错误场景无法穷举，建议重试前先通过卡详情、卡列表、卡流水或交易流水查询最终状态。

问：哪些错误代表执行结果未知，需要先查询最终状态？

答：卡服务异常、超时、客户端未收到响应，以及请求进入业务处理后发生的网络异常，均可能使执行结果处于未知状态。此时应先通过卡详情、卡列表、卡流水或交易流水查询最终结果。

问：错误码 400008 对应的 Sandbox 和 Production 限频、时间窗口及并发限制是什么？

答：目前 Sandbox 与 Production 的规则一致：

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

采用滑动窗口：分钟窗口为最近 60 秒，日窗口为最近 24 小时。

最大并发连接数为 1000。

问：触发限流时是否返回 Retry-After？

答：不返回。

10. 冻结、删除与撤销交易

问：CANCELLED 是否始终表示可以通过 ACTIVE 恢复的冻结状态？

答：状态定义如下：ACTIVE 表示激活，CANCELLED 表示禁用，DELETED 表示删除。在 /freezeCard 中，CANCELLED 表示冻结或停用，可以提交 ACTIVE 恢复；DELETED 状态不可恢复。

问：因 VM 风控关闭的卡是否也使用 CANCELLED？

答：VM 风控主动关闭卡片时使用 DELETED。因 CVV 或有效期连续输入错误三次而被发卡行冻结时，可能表现为 CANCELLED，一般等待 3 至 5 天后会自动解除。

问：冻结后是否仍会发生已授权交易的清算、撤销和退款？

答：取决于冻结前的交易状态。一般情况下，冻结后商户无法发起新的卡内扣款；退款和授权撤销金额仍会正常回到卡内。对于冻结前已批准的 Authorization，后续仍可能形成 Settlement，具体规则见后续补充确认。

问：/deleteCard 是否不可逆？

答：是，不可逆。

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

答：允许。删除时会先执行卡余额退回。

问：删除时卡内余额是否自动退回？

答：是。

问：删除后发生商户退款或争议款入账时，资金进入哪里？

答：卡片处于激活状态时，资金退回卡内；卡片已注销时，资金退回账户总账。

11. UAT 与 Production 契约

确认事项：

官方资料目前仅列出 Sandbox 和 Production，请确认是否另有独立 UAT 环境。

如无独立 UAT，请确认公开 OpenAPI 标注的 1.0.0 是否为当前 Production 契约版本，并说明 Sandbox 与 Production 在 Schema 或行为上的差异。

如 Production 的 RSA 方向、密钥位数、分块或编码方式与已确认的 Sandbox 契约不同，请列明差异。

已记录限流数值、滑动窗口、并发上限以及不返回 Retry-After。请确认限流所称“同一主体”是按 AppId、账户、子账户、出口 IP，还是组合维度计算。

答复：

目前对外仅提供 Sandbox 和 Production 两个环境，没有独立 UAT。Sandbox 用于系统集成及上线前测试。

Sandbox 与 Production 的业务报文加密格式一致。所有包含业务请求体的卡接口必须提交：

{
  "content": "RSA密文"
}

适用接口包括：

/createCard

/cardDetail

/freezeCard

/deleteCard

/rechargeCard

/refundCard

/cardTransaction

/updateCardLimit

/getCardList

/getCardFlow

/getProductCode 和 /getAccountBalance 没有业务请求体，可以提交空 Body。业务接口不支持直接提交明文 JSON。成功响应中的 data 为加密数据；参数、鉴权或解密失败时，错误响应为明文。

业务 API 当前按照 App/API Key 对应的 appId + 接口 维度限流；/getAccessToken 按照 来源 IP + 请求 URL 维度限流。

本次确认的 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. Request ID 与最终事实关联

确认事项：

已知相同 Request ID 会返回 Duplicate，不会返回首次请求结果，且当前没有统一的操作状态查询接口。

确认 Request ID 的去重登记与业务事务是否原子。

确认 IP 白名单、鉴权、限流、Hex/Base64/RSA 解密、参数校验以及进入业务处理前后的各阶段，是否会登记并消耗 Request ID。

flow_id 已确认为全局唯一，但 Request ID 与 flow_id 的映射仍需确认。除响应头回显及内部日志外，请确认 Request ID 是否写入 Card Flow、Transaction、Webhook 或财务明细。

如 Request ID 不进入最终事实表，请确认是否存在其他不可变 ID，可将一次写请求与最终事实一一关联。

答复：

X-Client-Request-Id 适用于全部 API，包括开卡、充值、退款、修改限额和删卡接口。规则如下：

最大长度为 64 个字符。

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

唯一性范围为 AppId + ClientRequestId。

该字段仅对已通过鉴权和解密、并进入业务 API 日志链路的请求生效并消耗 ClientRequestId。

当前永久保存。

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

不返回首次请求结果。

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

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

客户端未收到响应时，应按业务结果查询：

开卡：/getCardList 或 /cardDetail

充值及余额退回：/getCardFlow

消费交易：/cardTransaction

13. 冻结、待清算授权与删除后的迟到 Settlement

确认事项：

卡片在进入 CANCELLED 前已批准的 Authorization，冻结后是否仍可能形成 Settlement；如可能，资金如何扣取和查询。

自动退回卡余额与删除卡片是否属于同一原子事务。

自动退回失败时，删除是否整体失败并回滚。

自动退回对应的 flow_id 或财务关联字段是什么。

卡片删除后，迟到 Settlement 是否仍可能扣款；如可能，资金来源、负余额或追偿的表示方式，以及查询和对账方式是什么。

答复：

状态定义如下：

ACTIVE：激活。

CANCELLED：冻结或停用，可以提交 ACTIVE 恢复。

DELETED：删除，不可恢复。

VMCard 风控主动关闭卡片时使用 DELETED。因 CVV 或有效期连续输入错误导致的发卡行冻结可能表现为 CANCELLED，一般在 3 至 5 天后自动解除。

其他规则如下：

冻结后的退款和授权撤销金额可以正常回到卡内。

/deleteCard 不可逆。

卡内有余额或存在待清算授权时仍允许删除。

删除时会先执行卡余额退回。

卡片处于激活状态时，商户迟到退款回到卡内。

卡片已注销时，商户迟到退款进入账户总账。

删除卡片时的自动退款进入账户总账。

卡片删除后一般不会发生迟到 Settlement；如遇商户强制扣款，资金将从账户总账扣除，通常无法追偿。

相关资金变动可通过财务明细查询并进行对账。

14. 普通 Webhook 的 Production 运维资料

确认事项：

当前没有签名、Callback Secret、Nonce、独立 Event/Delivery ID 或 mTLS。

早期口径为普通 Webhook 按 HTTP Code 判断，响应 Message 不强制，超时为 30 秒，最多总计尝试 3 次，超时后重试且不保证投递顺序。

Production 上线前需确认固定出口 IP/CIDR、IPv4/IPv6 范围，以及地址变更通知和新旧地址重叠期。

明确哪些 HTTP Code 代表接收成功。

明确非成功 HTTP Code 是否适用“最多总计 3 次”，以及重试间隔和最长投递期。

明确投递日志查看方式和人工补发流程。

答复：

Production 当前固定出口 IP 为 8.219.3.65。如地址发生变更，将在对接群通知；客户完成配置变更后，VM 再执行相应切换。

客户调用 VM API 时，以响应体 code = 0 表示业务请求成功，非 0 表示失败。

Webhook 投递至客户接收地址时，建议接收端返回 HTTP 200 OK，并返回以下 JSON，以兼容当前交易流水类 Webhook 的成功判定：

{
  "msg": "ok"
}

如返回非 2xx、发生超时或网络异常，或者交易流水类 Webhook 的响应体中 msg 不为 ok，可能被视为投递失败，并触发重试或记录失败。

不同类别的投递规则如下：

VM API 异步回调类请求超时为 30 秒，但队列当前配置为 1 次尝试；失败后记录状态和错误信息，不应对外承诺自动重试 3 次。

交易流水类 Webhook 当前最多总计尝试 3 次。HTTP 4xx/5xx、网络异常、连接异常、超时或响应体不符合成功格式时，均视为投递失败并进入重试。

当前未配置固定重试间隔。实际重试时间受队列调度和 Worker 负载影响，不保证固定间隔或严格的最长投递期。

投递记录如下：

VM API 异步回调类提供投递记录表，可记录 request_id、callback_url、请求体、响应码、响应体、状态、失败原因及发送时间等信息。

交易流水类 Webhook 当前主要记录失败日志和队列日志，不提供完整的成功投递查询表。

15. 非空交易与普通 Webhook 验收

问：是否可以安排一种 Sandbox 或受控 Production 测试方式，生成一组可核对的 Authorization、Settlement、Reversal、Refund 及普通交易 Webhook，并同时核对 /cardTransaction、普通 Webhook、/getCardFlow（如适用）和财务明细？

答：N/A。

16. Request ID 与最终事实

确认事项：

Request ID 的去重登记与业务事务是否原子。

Request ID 是否进入 Card Flow、Transaction、Webhook 或财务明细；如未进入，是否存在其他不可变 ID，可将写请求与最终事实一一关联。

/getCardFlow 的 DECLINED 及其他失败状态是否一定为终局且没有资金或卡状态副作用，还是仍可能发生补偿、回滚或迟到成功。

是否存在业务尚未终局时写接口已经返回成功的情况。

写入成功后，卡、Flow、Transaction 或财务事实的最大传播延迟，以及空查询结果何时可以作为成熟的否定证据。

答复：

X-Client-Request-Id 的去重登记发生在 VM API 日志中间件，与后续业务表写入不属于同一个数据库事务，因此不能承诺其与业务事务原子一致。

该 ID 不作为稳定字段写入 Card Flow、Transaction 等最终事实表。VM API 异步回调会优先将其用作回调 request_id，但它不是交易、资金或卡片事实的一一关联键。

/getCardFlow 查询的是卡充值和卡余额退回账户等资金流水，不是消费交易生命周期流水。

DECLINED 表示该笔资金流水处理失败，PENDING 表示处理中，COMPLETE 表示完成。DECLINED 可以作为该笔 Flow 的失败状态，但不能单独作为全链路最终资金结论。

部分写接口返回成功，仅表示 VM API 或卡服务已成功受理请求，或已完成当前同步处理步骤，不代表所有后续通道状态、资金清算、迟到交易或异步回调均已终局。

客户端不应仅依据写接口的成功响应判断最终结果，应以后续查询、回调、余额及交易或资金流水为准。

当前没有可对外承诺的固定最大传播延迟。

17. 时间与异常流水

问：/cardTransaction.auth_time 是否采用目标产品固定时区？如未固定，如何获取每条记录的 Timezone 或 UTC Offset？Sandbox 中曾出现一笔 /getCardFlow 流水为 amount = -10、reality_amount = 0，但余额实际变化为 10，其最终账务语义是什么？

答：/cardTransaction.auth_time 当前不返回 Timezone 或 UTC Offset 字段。记录时间来自各通道交易处理后的入库值。该笔异常流水的最终账务语义仍需结合通过受控渠道提供的原始流水进一步确认。

18. 目标产品的交易关联字段

问：目标产品是否提供供应商父交易 ID、清算或退款父子字段，或者其他稳定的扩展关联键？

答：无扩展字段。

19. 冻结、删除与迟到扣款

确认事项：

哪些阶段或状态下的已批准 Authorization 在卡片冻结后仍可能形成 Settlement，以及届时从卡可用余额还是账户总账扣款。

删除前自动退回卡余额与删除操作是否属于同一原子事务；自动退回失败时，删除是否整体失败并保持原卡状态。

目标 Production 产品在删卡自动退余额时，是否生成带唯一 flow_id 的 card refund，以及其与 /deleteCard 请求、财务明细之间是否存在稳定关联字段。

迟到 Settlement 导致账户资金不足时，API 或控制台如何表示负值、冻结、欠款或其他受限状态，是否存在结构化告警。

答复：

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

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

迟到 Settlement 优先从卡内余额扣除；卡内余额不足时，从主账户总账扣除。

删除前自动退回卡余额与删除操作属于同一原子事务。自动退回失败时，删除操作整体失败，并保持原卡状态。

账户总账金额可以在控制台显示为负数。

账户余额不足时，API 开卡返回错误码 700004。

当前不提供结构化告警。

暂无删卡自动退余额对应的 flow_id 及其稳定关联字段。

20. Chargeback、Dispute 与其他扣回事件

问：目标产品是否支持 Chargeback、Dispute 或其他资金扣回扩展事件？如支持，请提供其在 /cardTransaction、Webhook 及财务明细中的字段、枚举和资金动作。

答：N/A。

21. `/refundCard` 是否支持将卡余额精确退至零

问：

请分别确认当前目标储值卡（save）产品在 Sandbox 和 Production 环境中，调用 /refundCard 时，amount 是否允许精确等于调用时卡片的全部 available_amount，并使退款后的卡余额精确为 0.00 USD。

环境	需要确认的事项
Sandbox	是否允许 `amount = available_amount`，并使卡余额精确变为 `0.00 USD`。
Production	是否允许 `amount = available_amount`，并使卡余额精确变为 `0.00 USD`。

如不允许，请提供 /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 两个环境的处理口径一致。

22. Hosted Reveal 或其他受控卡数据揭示能力

问：

请确认是否提供以下任一能力，使完整卡数据无需进入客户的普通应用系统：

VM 托管的卡数据展示页面。

可嵌入的 iframe。

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

其他由 VM 托管的受控卡数据揭示方式。

如提供，请同时说明：

Sandbox 是否可用。

接入方式及鉴权模型。

Token 或链接的有效期、一次性使用及失效规则。

可提供的审计记录。

所需请求字段及返回字段的脱敏清单。

答：

当前暂不提供 Hosted Reveal、iframe、一次性或短时卡数据展示 Token/链接，也不提供其他由 VM 托管的受控卡数据揭示方式。

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

问：商户主动发起的退款出现在哪个数据通道？是在 /getCardFlow 中以某种 type 返回，还是在交易查询接口中以某种 transaction_type 返回，或者两个接口都会返回？

答：商户主动退款主要通过 /cardTransaction 返回，同一笔商户退款事件不会同时作为 /getCardFlow 流水返回。各类型的业务含义如下：

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

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

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

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

24. 原交易关联、金额语义及终态标志

问：退款记录如何关联原始消费，是否包含原交易的 auth_id 或类似字段？金额字段的语义是什么，退款完成的终态标志是什么？

答：当前只能确认退款记录与原消费属于同一张卡，无法通过现有对外字段稳定关联至某一笔具体原交易。退款金额以正数返回，调用方应根据交易类型判断资金方向，不应通过金额正负判断。

退款完成应同时满足以下条件：

type = "Refund" AND status = "COMPLETE"

25. Webhook 覆盖范围、事件类型及载荷字段

问：控制台配置的 Webhook 是否覆盖商户主动退款？如覆盖，事件类型和载荷字段有哪些？

答：配置交易 Webhook 后，已经落库并触发转发的退款记录会通过同一回调地址异步通知。退款事件的 type 为 Refund。Webhook 载荷字段如下：

参数名	类型	说明
`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	交易详情或交易失败信息

26. Sandbox 商户退款模拟方式

问：Sandbox 环境如何模拟商户退款，以便开展联调测试？

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

FAQ

VM Open API 技术问答与确认记录#

文档说明#

1. 费率与计费口径#

1.1 充值费#

1.2 开卡费#

1.3 其他费用#

2. 鉴权与报文加密#

2.1 实际请求格式#

2.2 RSA 长报文处理#

2.3 VM 公钥与密钥轮换#

3. Access Token#

4. 请求幂等与最终结果查询#

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

5.1 产品信息#

5.2 save 与 share#

5.3 地址与持卡人字段#

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

7. 交易记录与对账#

7.1 交易关联#

7.2 查询与分页#

7.3 金额与手续费#

8. Webhook 与 3DS 通知#

8.1 来源验证#

8.2 字段与投递规则#

8.3 3DS#

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

10. 冻结、删除与撤销交易#

11. UAT 与 Production 契约#

12. Request ID 与最终事实关联#

13. 冻结、待清算授权与删除后的迟到 Settlement#

14. 普通 Webhook 的 Production 运维资料#

15. 非空交易与普通 Webhook 验收#

16. Request ID 与最终事实#

17. 时间与异常流水#

18. 目标产品的交易关联字段#

19. 冻结、删除与迟到扣款#

20. Chargeback、Dispute 与其他扣回事件#

21. /refundCard 是否支持将卡余额精确退至零#

22. Hosted Reveal 或其他受控卡数据揭示能力#

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

24. 原交易关联、金额语义及终态标志#

25. Webhook 覆盖范围、事件类型及载荷字段#

26. Sandbox 商户退款模拟方式#

VM Open API 技术问答与确认记录

文档说明

1. 费率与计费口径

1.1 充值费

1.2 开卡费

1.3 其他费用

2. 鉴权与报文加密

2.1 实际请求格式

2.2 RSA 长报文处理

2.3 VM 公钥与密钥轮换

3. Access Token

4. 请求幂等与最终结果查询

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

5.1 产品信息

5.2 save 与 share

5.3 地址与持卡人字段

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

7. 交易记录与对账

7.1 交易关联

7.2 查询与分页

7.3 金额与手续费

8. Webhook 与 3DS 通知

8.1 来源验证

8.2 字段与投递规则

8.3 3DS

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

10. 冻结、删除与撤销交易

11. UAT 与 Production 契约

12. Request ID 与最终事实关联

13. 冻结、待清算授权与删除后的迟到 Settlement

14. 普通 Webhook 的 Production 运维资料

15. 非空交易与普通 Webhook 验收

16. Request ID 与最终事实

17. 时间与异常流水

18. 目标产品的交易关联字段

19. 冻结、删除与迟到扣款

20. Chargeback、Dispute 与其他扣回事件

21. `/refundCard` 是否支持将卡余额精确退至零

22. Hosted Reveal 或其他受控卡数据揭示能力

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

24. 原交易关联、金额语义及终态标志

25. Webhook 覆盖范围、事件类型及载荷字段

26. Sandbox 商户退款模拟方式