环境与测试

​

测试环境的行为

• 您创建的任何操作都会被接受，并在几秒后（默认约 10 秒）达到 completed，触发与 live 相同的 webhook。
• 特定的魔法值可以强制触发其他所有结果，让您无需猜测即可测试 失败处理逻辑。

​

魔法值

​

PIX 二维码示例（巴西 QR 出金）

00020126360014br.gov.bcb.pix0114+5511998765432520400005303986540575.005802BR5913LOJA DA MARIA6009SAO PAULO62110507PED423163040BF9

00020126380014br.gov.bcb.pix0116loja@example.com5204000053039865802BR5913LOJA DA MARIA6009SAO PAULO62070503***63045EFE

00020126360014br.gov.bcb.pix0114+5511998765432520400005303986540580.995802BR5913LOJA DA MARIA6009SAO PAULO62110507PEDFAIL63045211

​

与 live 的差异

• 任何真实的资金、卡片、邮件或短信都不会离开测试环境。
• 账户生而已验证：每个新的测试账户都以 kyc_status: approved 开始，因此您可以立即演练所有产品 —— 没有入驻闸门。在 live 中， 账户生而未验证，必须先完成 KYC/KYB 才能转出资金。
• 账户生而带有数据：每个新的测试账户都自带约 6 个月的真实感演示 历史，覆盖所有产品（payouts、payins、转账、加密、兑换、卡片、 banking、联系人……），余额、对账单和分析报表开箱即用 —— 您可以在 创建任何操作之前就构建仪表盘和报表。
• 银行目录是虚构的（Simulated National Bank 等）。
• 汇率是真实的（与 live 同源），因此金额看起来真实。
• 测试数据与 live 完全独立：不从生产复制任何内容。请将测试数据视为 可丢弃的。

​

从控制台使用测试模式

​

在本地开发中测试 webhook

# 安装 cloudflared 并暴露本地端口
cloudflared tunnel --url http://localhost:3000
# → https://<random>.trycloudflare.com  ← 用作 callback_url

ngrok http 3000
# → https://<random>.ngrok-free.app  ← 用作 callback_url

curl -X POST https://cryptobank.qbank.cl/platform/v1/webhooks/subscriptions \
  -H "X-API-Key: pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "payin_credited",
    "callback_url": "https://your-tunnel.trycloudflare.com/webhooks/cbpay",
    "secret": "a-long-random-secret"
  }'

​

在测试环境演练每个流程

​

上线前检查清单

• 将 base URL 换成 https://api.qbank.cl/platform，密钥换成您在 live 模式签发的 pk_...。
• API 密钥保存在密钥管理器中（绝不放在前端或代码仓库）。
• 每个资金操作都发送由您内部 id 派生的 idempotency_key（不是每次尝试随机生成的 UUID）。
• 遇到超时或 5xx 时不要换新密钥重试：使用相同密钥重试，或用 GET 查询状态。
• 验证每个 webhook 的 HMAC 签名并快速返回 2xx（异步处理）。
• 正确处理非终态（pending、processing），不要假设成功 —— live 的清算时间比模拟的 10 秒更长。
• 在 live 重新创建了 webhook 订阅（test 的订阅不会迁移）。
• 查询 GET /v1/services 只展示已启用的产品 —— 见服务。
• 每天通过 GET /v1/movements 或对账单对账。
• 与 CBPay 团队保持沟通渠道，处理 unassigned 充值或事故。