首充預覽
開卡首充的只讀試算。給定 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 | 服務端異常 |