首充预览
开卡首充的只读试算。给定 first_deposit_amount，它计算 /card/apply 将要收取的明细——超额部分的手续费、到卡金额、钱包冻结合计——但不开卡、不写库、不冻结资金。
用于在客户确认前展示「将要支付多少」的明细，数值与真正开卡 1:1 一致。
什么是首充
卡配置定义了一个底额（base_amount），按 1:1 进卡、不收手续费。商户可在开卡时传更大的 first_deposit_amount 加充；超出底额的部分（超额）按充值口径收取手续费，扣费后按 1:1 进卡（USDT/USD，不走汇率）。最终发给提供方的首充始终为整数。
配置还可以另设首充最低金额（min_first_deposit_amount，恒 ≥ base_amount）：首充总额 first_deposit_amount 必须不低于该值，但只有底额部分免手续费。例如 base_amount=10、min_first_deposit_amount=500 → 至少首充 500，其中 10 免手续费、490 按充值费率收费。
端点
| 项 | 值 |
|---|---|
| Method | POST |
| Path | /api/v1/openapi/card/first_deposit/preview |
| 鉴权 | HMAC |
| 幂等 | 无需（只读） |
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
header_id | string | ✅ | hdr_<id> 格式（列卡头） |
package_id | string | ✅ | pkg_<id> 格式（列卡配置） |
first_deposit_amount | string | 可选 | 首充总额，非负整数，单位为支付/充值资产（如 USDT）。空 = 用配置底额。必须 >= min_first_deposit_amount（该值本身 ≥ base_amount）；首充最低高于底额时，留空会被 first_recharge_below_min 拒绝。科学计数法、小数、符号一律拒绝。 |
请求示例
json
{
"header_id": "hdr_119",
"package_id": "pkg_33",
"first_deposit_amount": "16"
}响应字段
始终返回 200（优雅语义）
即便金额不可提交，本接口也返回 200。用 is_valid 判断开卡是否会成功，用 invalid_reason 取稳定原因码。仅当 ID 非法、卡类型不支持或服务端故障时才返回非 200。
| 字段 | 类型 | 说明 |
|---|---|---|
package_id | string | 回显，pkg_<id> |
card_type | string | 小写业务码，如 virtual_v |
currency | string | 卡内币种（如 USD） |
pay_asset_symbol | string | 支付/充值资产符号（如 USDT） |
open_card_fee | string（小数） | 开卡费（支付资产） |
base_amount | string（小数） | 底额——1:1 进卡、不收费 |
min_first_deposit_amount | string（小数） | 生效首充最低金额（max(base_amount, 套餐/卡头首充最低)，含底额）。first_deposit_amount 必须 ≥ 该值；该值高于 base_amount 时留空（默认底额）会被拒绝 |
request_amount | string（小数） | 本次试算的首充总额 |
excess_amount | string（小数） | 超出底额的部分（request_amount − base_amount） |
excess_fee_amount | string（小数） | 超额手续费（手续费资产） |
excess_fee_asset_symbol | string | 手续费资产符号（无超额时省略） |
excess_settle_amount | string（小数） | 超额扣费后金额（取整进卡前） |
excess_card_amount | string（小数） | 超额实际到卡金额（取整后） |
exchange_rate | string | 兼容字段；USDT/USD 1:1，恒为空 |
first_recharge_card | string（小数） | 卡内首充合计（底额 + 到卡超额）；整数 |
total_freeze | string（小数） | 支付资产的钱包冻结合计（开卡费 + 卡内到账 + 超额手续费 + 押金，仅当 deposit_in_total_freeze=true）；取整尾差不收取 |
deposit_required | bool | 本次开卡会不会冻结开卡押金（与 /card/apply 同一准入判定：模式 2 恒 true；模式 3 仅 KYC 未达标时；模式 4 达标后） |
deposit_amount | string（小数） | 押金金额（押金资产单位）；不收押金时 "0" |
deposit_asset_symbol | string | 押金资产符号（如 USDT / USD）；不收押金时为空 |
deposit_refund_days | int | 销卡后多少天可申请退押金（0 = 销卡后即进入退款审核） |
deposit_in_total_freeze | bool | true = 押金资产与支付资产相同，押金已并入 total_freeze；false = 未并入（不收押金，或资产不同需单独展示） |
deposit_wallet_balance | string（小数） | 押金资产可用余额；不收押金时 "0" |
deposit_wallet_balance_sufficient | bool | 按真实开卡冻结顺序（先开卡费+首充、后押金；USDT 不足按 USD 1:1 补足）模拟后押金能否冻结成功；不收押金时恒 true |
fee_type | int | 充值手续费类型：1=固定 2=百分比 3=混合 |
fee_rate | string | 费率（百分比/混合时）；否则省略 |
fee_fixed | string | 固定费（固定/混合时）；否则省略 |
min_recharge_amount | string（小数） | 配置最小充值（展示用） |
max_recharge_amount | string（小数） | 配置最大充值——超额受此上限约束 |
wallet_balance | string（小数） | 你账号在支付资产下的可用余额 |
wallet_balance_sufficient | bool | 余额（含 USD 1:1 补足）是否够冻结 total_freeze |
usd_balance | string（小数） | 你的 USD 余额（仅用于 USDT→USD 1:1 补足判定） |
will_use_usd | bool | 是否会用到 USD 1:1 补足 |
usd_needed | string（小数） | 经补足会动用的 USD 金额 |
is_valid | bool | 用此金额开卡是否会被受理 |
invalid_reason | string | is_valid=false 时的稳定原因码（有效时省略） |
warnings | string[] | 可选提示码 |
响应示例（可提交）
json
{
"code": 200,
"message": "成功",
"data": {
"package_id": "pkg_33",
"card_type": "virtual_v",
"currency": "USD",
"pay_asset_symbol": "USDT",
"open_card_fee": "1.000000000000000000",
"base_amount": "10",
"min_first_deposit_amount": "10",
"request_amount": "16",
"excess_amount": "6",
"excess_fee_amount": "1.22",
"excess_fee_asset_symbol": "USDT",
"excess_settle_amount": "4.78",
"excess_card_amount": "4",
"first_recharge_card": "14",
"total_freeze": "16.22",
"deposit_required": false,
"deposit_amount": "0",
"deposit_asset_symbol": "",
"deposit_refund_days": 0,
"deposit_in_total_freeze": false,
"deposit_wallet_balance": "0",
"deposit_wallet_balance_sufficient": true,
"fee_type": 3,
"fee_rate": "0.020000",
"fee_fixed": "1.100000000000000000",
"min_recharge_amount": "10.000000000000000000",
"max_recharge_amount": "100.000000000000000000",
"wallet_balance": "70.82999088",
"wallet_balance_sufficient": true,
"usd_balance": "0",
"will_use_usd": false,
"usd_needed": "0",
"is_valid": true
}
}本例中：base=10 的配置上首充 16，10 按 1:1 免费进卡，超额 6 收取 1.22 手续费、剩 4 进卡——故卡内到账 14，钱包冻结 16.22。
响应示例（不可提交）
json
{
"code": 200,
"message": "成功",
"data": {
"package_id": "pkg_33",
"card_type": "virtual_v",
"is_valid": false,
"invalid_reason": "first_recharge_exceeds_max",
"base_amount": "10",
"min_first_deposit_amount": "10",
"request_amount": "9999",
"max_recharge_amount": "100.000000000000000000"
}
}invalid_reason 原因码
is_valid=false 时会附带以下稳定原因码之一（与开卡返回的 message_key 同 key）：
| invalid_reason | 含义 |
|---|---|
invalid_first_deposit_amount | 不是纯非负整数（小数 / 符号 / 科学计数法 / 位数过多） |
first_recharge_below_base | 金额低于 base_amount |
first_recharge_below_min | 金额低于 min_first_deposit_amount（未传 first_deposit_amount 而首充最低高于底额时同样返回） |
first_recharge_exceeds_max | 超额超过 max_recharge_amount |
first_recharge_limit_exceeded | 超额超过账号充值限额 |
first_recharge_asset_mismatch | 开卡费资产 ≠ 充值资产；该配置不支持自定义超额 |
first_recharge_excess_too_small | 扣费 + 取整后到卡为 0，请加大金额 |
insufficient_balance | 钱包（含 USD 补足）不足以冻结 total_freeze |
kyc_required | 该卡 KYC 为硬门槛且账号未达标（与 /card/apply 的拒绝一致） |
card_deposit_config_invalid | 准入模式要求收押金但平台侧押金参数不齐，修好前谁都开不了 |
card_deposit_insufficient_balance | 押金资产余额不足以冻结 deposit_amount（仅押金资产 ≠ 支付资产时可能单独出现） |
bank_card_config_not_found | 套餐未启用 / 不存在 |
bank_card_header_not_found | 卡头未启用 / 不存在 |
典型错误
非 200 响应（入参非法 / 卡类型不支持 / 服务端故障）：
| HTTP | message_key | 说明 |
|---|---|---|
| 400 | openapi_invalid_header_id | header_id 缺失 / 前缀错误 / 不存在 |
| 400 | openapi_invalid_package_id | package_id 缺失 / 前缀错误 |
| 400 | openapi_card_type_not_supported | header 对应的卡类型不在虚拟卡范围 |
| 400 | account_manager_bind_required / account_manager_unavailable / account_manager_open_disabled | 账号不可开的客户经理管控卡头（与 apply 同口径） |
| 401 | openapi_invalid_credentials | 鉴权失败 |
| 500 | openapi_first_deposit_preview_failed | 服务端异常 |