CardV 商户 API

#文档目录

#环境

沙盒是一套独立的测试环境，里面用的是测试金。两个环境的 API Key、余额、订单和商品编号都互不相通。

#快速开始

1. 注册：在商户后台申请商户账号，并验证邮箱。

2. 等待审核：CardV 审核你的企业资料，通过后你会拿到商户号（Merchant ID），例如 M00000001。

3. 进入沙盒：登录商户后台，在顶部切换到 Sandbox。系统会送你 1,000 USD 测试金。

4. 创建 API Key：在后台进入 Integrations → API keys。创建一个 Key。后台只会显示一次 Key ID 和签名密钥，请把签名密钥保存到你的密钥管理系统里。

5. 查询余额：

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_KEY_ID=ck_test_...            # shown in the Portal
   export CARDV_SIGNING_SECRET=cs_test_...    # from your secret store
   
   cardv_get() {  # every call is signed, see Authentication
     local ts nonce sig
     ts=$(date +%s); nonce=$(openssl rand -hex 16)
     sig=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$ts" "$nonce" \
       e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 \
       | openssl dgst -sha256 -hmac "$CARDV_SIGNING_SECRET" -hex | sed 's/^.*= //')
     curl -sS "$CARDV_BASE$1" -H "X-Key-Id: $CARDV_KEY_ID" \
       -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" -H "X-Signature: $sig"
   }
   
   cardv_get "/api/v1/balance"

6. 查找商品：

   ShellCopy

   cardv_get "/api/v1/skus?search=steam&limit=20"

   选一个 "availability": "available"（可售）的商品，记下它的 sku_id。

7. 获取价格：

   ShellCopy

   cardv_get "/api/v1/skus/S000001/quote?quantity=1"

   记下 merchant_price，这就是你购买一件的价格。

8. 下单：和所有请求一样，需要签名。用认证与签名里的示例代码，发送下面的内容：

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.25"}
     ]
   }

   成功后返回 HTTP 201，以及 CardV 订单号，例如 O-00001234。

9. 获取卡密：调用 GET/api/v1/orders/O-00001234，直到订单状态变为 succeeded。卡密在 items[].deliveries[] 里：card_number、pin_code 和 redeem_url。你也可以配置 Webhook，在订单完成时收到通知。

10. 上线：完成沙盒测试清单后切换到正式环境。

以上编号和价格只是示例，请以你账户实际返回的数据为准。

#接口一览

API 一共只有 16 个接口，路径都以 /api/v1 开头。

用 API Key 调用其他任何接口，都会返回 HTTP 403：

{"detail": "This operation is only available in the Merchant Portal."}

话费充值的说明见话费充值。

#编号说明

编号请按文本保存，不要去解析其中的数字。详见通用约定。

#在商户后台完成的操作

• 钱包加款，以及余额不足提醒
• 历史订单查询和导出
• 订单发票
• 资金流水与对账
• Webhook 配置、推送记录和重新推送
• API Key 管理
• IP 白名单
• 团队成员与角色
• 操作日志
• 两步验证（2FA）
• 在正式环境和沙盒之间切换

#兼容性与支持

我们可能会在不另行通知的情况下，新增返回字段和新的状态值。遇到不认识的字段请直接忽略；遇到不认识的订单状态，一律按"尚未完成"处理。不要依赖错误信息的具体措辞。

如需帮助，请发邮件至 [email protected]，写明商户号、环境、相关订单号、发生时间（UTC）和 HTTP 状态码。切勿在邮件中发送 API Key、签名、Webhook 密钥或卡密。