沙盒环境

相关文档：概览 · 认证与签名

#开通沙盒

1. 你的企业资料需要先通过 CardV 审核。
2. 登录商户后台，在顶部切换到 Sandbox。沙盒不能直接登录，只能从后台切换进入。
3. 第一次进入时，CardV 会为你创建沙盒账户，商户号不变，并附带 1,000 USD 测试金。
4. 在沙盒中，由 Owner 创建并查看一个沙盒 API Key。正式环境的 Key 在这里不能用。
5. 可选：配置沙盒 Webhook，它有独立的签名密钥。

#与正式环境的区别

• 沙盒有独立的 API Key、钱包、订单、Webhook、IP 白名单和操作日志。
• 设置不会互通。Key、Webhook 和 IP 白名单需要在两个环境分别配置。
• 沙盒订单不会采购真实商品，测试卡密无法兑换。
• 测试金没有实际价值：沙盒不能加款，不能提现，也不能转到正式环境。
• 测试金用完后，可以联系 CardV 支持补充。

#测试金

沙盒订单扣测试金的方式，和正式环境扣真实资金完全一样。失败的测试订单也会同样退款。测试金的变动可以在商户后台的资金流水页面查看。

#测试商品

• 沙盒商品很少，而且都是测试商品。
• SKU 编号和正式环境不同，请始终在沙盒里通过 GET/skus 查询。
• 不要把沙盒的编号复制到正式环境的配置里，反之亦然。
• 沙盒里的价格、库存和发货速度与正式环境不同。

#测试清单

• GET/account 返回你的商户号，且 "api_access_enabled": true。
• GET/balance 调用正常。
• 能够翻页读取 GET/skus，并且只购买可售（available）的 SKU。
• 签名正确的订单下单成功；签名错误时返回 HTTP 403。
• 每个订单行都传了 expected_unit_price。
• 自选面值 SKU 带 amount 下单成功（如果沙盒里有这类商品）。
• 同一笔订单提交两次（新的随机串，相同的内容和商户订单号），返回 HTTP 200 和相同的 order_id，余额只扣一次。
• 相同的商户订单号、不同的订单内容，返回 HTTP 400，错误字段为 external_order_id。
• 请求超时后，你的代码会重新提交同一笔订单，而不是换一个新的商户订单号。
• 能读取 deliveries[].display_fields 并交付给客户。
• 能正确处理 failed、refunded 和 partially_succeeded。
• Webhook 验签代码先通过测试数据，再通过真实的沙盒推送，并且能忽略重复消息。
• 收到 HTTP 429 后会按 Retry-After 等待。
• 日志里没有 API Key、签名、卡密或客户账户信息。

#上线清单

• 在正式环境后台创建正式 API Key，保存到生产环境的密钥管理系统。
• 在配置里把接口地址改为 https://b2b.cardv.net/api/v1。
• 读取正式环境的商品，把你的商品对应到正式环境的 SKU 编号。
• 在商户后台给正式钱包加款，并设置余额不足提醒。
• 可选：把服务器 IP 加入正式环境的 IP 白名单。
• 配置正式环境 Webhook，并部署它的签名密钥。
• 与 CardV 确认你的订单限额和频率限制。
• 先下一笔小额正式订单，核对扣款、卡密和 Webhook，然后再逐步放量。
• 每天通过商户后台的资金流水和导出功能对账。
• 所有 Owner 都开启两步验证。

#常见问题

HTTP 403 error code: 1010

沙盒前面有一层网络防护服务，部分 HTTP 客户端会收到 HTTP 403，内容是纯文本 error code: 1010。这说明请求没有到达 CardV，更换 Key 或修改签名都没有用。

• 设置一个能识别你系统的 User-Agent。
• 如果仍然出现，请把服务器 IP、User-Agent 和发生时间发给 CardV 支持。
• 不要因此改为直接在正式环境测试。