> ## Documentation Index > Fetch the complete documentation index at: https://docs.cbpayapp.com/llms.txt > Use this file to discover all available pages before exploring further. # 更新日志 > API 与文档变更历史 CBPay API 及本文档的每一次变更，最新的排在最前。 破坏性变更会提前公告，并标注为 **Breaking**。 **新增** * **对外支付的合规控制**（[出金指南](/zh/guides/payouts)、[错误](/zh/errors)）：出金、带受益人姓名的加密货币提现以及 collect 收款现在会在**资金移动之前**经过额外的合规控制。已记录的错误：`403 compliance_hold`（操作被拦截且未被创建 —— 未扣款；按政策不披露具体原因，请携带时间戳联系支持）与 `503 compliance_check_unavailable`（合规校验暂时无法完成；操作未被创建 —— 请使用**相同的** `idempotency_key` 重试）。 **修复** * **AML 筛查的个人字段格式**（[指南](/zh/guides/aml)）：筛查引擎要求 `date_of_birth` 为 `{year, month, day}` 对象（纯字符串 `"YYYY-MM-DD"` 返回 `422`）、`nationality` 为 ISO-3166 代码的**数组**、 `personal_identification[]` 为 `{ "issuing_country", "number" }` 且不带 `type` 字段。指南与 spec 示例已按实测验证的格式更新。 **新增** * **QR Crypto POS — 面向处理商的定额加密货币二维码收款**（[指南](/zh/guides/qr-pos)）： 运营实体 POS 终端的企业账户可将其商户注册为已验证商户（已批准的第三方 KYB/KYC），并按笔生成带专属地址和二维码的加密货币收款（USDT、USDC、 BTC）。面向 POS 的支付早期检测（数秒内 `confirming`）、入账并自动兑换 为结算资产、收款/webhook 按商户归属、对账汇总（`GET /v1/pos/summary`， 含按商户的信息性佣金与应分配净额），以及经加密货币提现通道的退款并带 硬上限（绝不超过已收金额）。新路由位于 `/v1/pos/*`（API 参考中的 QR Crypto POS 标签）；部分支付会累计，过期收款收到的迟到支付同样入账。 **修复** * **比特币加密货币二维码**：结账页二维码现在使用裸 bech32 地址（与 TRON/ETH 相同）。Binance 等交易所应用会将 BIP-21 URI （`bitcoin:…?amount=…`）判为「无效二维码」；精确金额仍显示在旁边 并可复制。 * **收款页**：白标 favicon（组织符号），面板文案不再在词中间断行 （「momento」被拆成「moment」/「o」）— 激进的 `word-break` 仅保留 在等宽地址上。 **新增** * **每个收款链接的专属 CLABE（墨西哥）**：在通用收款链接上生成墨西哥 `bank_transfer` 支付选项时，现在会签发（或从可回收池中取出）一个 **该链接专属**的 CLABE。付款人只需转账精确金额，**无需填写参考码**： 入账会按收款账户自动检测并路由到该链接。支付选项的 payload 中 `destination` 带有 `dedicated: true`；若无法签发专属账户，则降级为 传统方式（商户账户 + 转账附言中必填 `reference`）。链接结清后 （已支付或已过期），CLABE 经过冷却期后回收再用。 **新增** * **通用收款链接支持拉取式收款（委内瑞拉）**：结账页面现在提供直接从付款人 账户扣款的方式（委内瑞拉的 `c2p` 和 `debito_inmediato`）。付款人在同一 页面填写银行、证件号、电话或账户以及 OTP；金额始终是报价时冻结的金额。 新增公开端点：`POST /pay/{token}/collect/otp`（通道按需发送密码时请求 OTP）和 `POST /pay/{token}/collect`（执行扣款；若通道同步确认，链接在 同一次调用中完成结算）。这些方式在 `GET /pay/{token}/quote` 目录中带 `collect: true`。 * **按国家的多币种法币**：报价中的每个国家在 `options[]` 中列出其通道 — 每个方式+币种一行（例如玻利维亚同时提供 BOB **和** USD 的二维码），并在 `country_quote` 中带各自的 `local_amount`。生成以多种币种提供的方式时 必须传 `¤cy=YYY`（`400 currency_required` 错误现在适用于任何 方式，不再只限银行卡）。 * **银行转账的目标账户**：当通道使用专属收款账户时（墨西哥的 CLABE）， `bank_transfer` 的生成结果除参考码外还包含 `destination`（类型、账号和 收款人）— 付款人无需离开页面即可知道转账目标。 **变更** * **支付页面改用 SVG 旗帜**：国家和币种旗帜现在是 SVG 图片（在 Windows、 macOS 和移动端显示一致；此前部分系统会把国家代码显示为纯文本）。银行卡 页签的旗帜按**扣款币种**推导（USD → 美国国旗，即使收单机构位于其他 国家）。 **修复** * 结账页面不再因为只是打开着就返回 `429 too_many_attempts`：读取、生成、 OTP 和扣款的流量限制现在彼此独立。 **新增** * **通用收款链接新增"银行卡"标签页**：银行卡支付从 Fiat 标签页移到 独立的标签页，按**扣款币种**列出（目前为 BOB 和 USD；未来收单机构 的币种会自动出现）。`GET /pay/{token}/quote` 返回新的 `cards[]` 目录（每个选项含国家、币种和 `local_amount`），`countries[]` 的 方式列表不再包含 `card`。物化银行卡须指定币种： `POST /pay/{token}/methods/card?country=XX¤cy=YYY` —— 缺失时 返回新错误 `400 currency_required`。每种币种是独立的物化，各自有 托管支付页面。 **变更** * **支付页面视觉升级**：金额旁及加密货币分组显示资产 Logo（USDT、 USDC、BTC、GOLD），Fiat 选择器和银行卡行显示国旗，各方式带图标， 并新增**醒目的到期计时器**（带时钟的胶囊；1 小时内显示倒计时， 10 分钟内变红）。 **修复** * 结账页面不再每隔几秒自动滚动到当前面板：自动刷新仅在数据变化时 重新渲染且不移动滚动条（只有手动选择支付方式才会将详情滚入视图）。 **变更** * **通用收款链接支付页面全新改版**：支付选项现组织为三个标签页 —— **CBPay**（商户二维码 + 别名，附复制按钮）、**Crypto**（币种按网络 分组；新网络启用后自动出现）和 **Fiat**（国家选择器 + 各国支付方式 及即时报出的当地金额）。别名、地址、金额和参考号均带复制按钮。API 无任何变化：URL、创建契约和公开端点（`/state`、`/quote`、 `/methods/{method}`）保持不变。 **修复** * **QR 出金——在创建 payout 之前进行校验**：`POST /v1/payouts/qr/scan` 遇到不可读或动态二维码时，现在返回 `400 invalid_qr_payload` 及具体原因 （之前返回泛化的 `502`）。在巴西的 confirm 中，金额与固定金额 PIX 二维码不一致时返回 `422`，出金为 `failed` 且**退款已自动完成**—— 二维码保持有效，可用正确金额和新的键重试。 * **静态 PIX 二维码可复用**："一个 QR = 一笔支付" 的守卫不再适用于巴西的 静态 PIX 二维码（它们天生会被支付多次）；每笔支付的保护是您的 `idempotency_key`，在巴西的每次 confirm 中均为必填。 **新增** * **巴西 PIX 二维码出金（BR/BRL）**：两步流程 `POST /v1/payouts/qr/scan` → `POST /v1/payouts/qr/confirm` 现已接受巴西的 **静态** PIX 二维码（含 "copia e cola" 代码）——传 `country: "BR"` 与 `currency: "BRL"`。扫码在本地解码 BR Code（免费），返回商户名称、PIX 密钥与金额；确认步骤通过 PIX 付款，计费与常规 payout 完全相同。`amount` 始终必填：固定金额二维码要求金额完全一致（不一致时返回 `422`，出金为 `failed` 且自动退款——该二维码**不会**作废）。静态 PIX 二维码**可复用**： 每笔支付携带自己的 `idempotency_key`。动态或损坏的二维码返回 `400 invalid_qr_payload`——请改用 `pix` 方式并提供收款人的密钥。 测试环境已提供示例二维码与魔法值（`.99` 金额失败）—— 见[测试环境](/zh/environment-testing#pix-二维码示例巴西-qr-出金)。详见 [payouts 指南](/zh/guides/payouts#qr-出金)。 **变更** * **通用收款链接 v2 —— 多国家 + 结算到您选择的余额**（相对昨天 v1 形态为 **Breaking**）：收款现在通过 `settlement_asset` 以您 4 个虚拟余额中的任意 一个计价（默认 `USDT`，可选 `USDC`、`BTC`、`GOLD`），`amount` 以该资产 计（"50" USDT、"0.001" BTC、"2" 克黄金）；传 `currency` 将返回 `400` （已存在的 v1 链接继续有效）。付款人可以看到**所有有可用收款通道的国家** （选择国家 → 显示该国方式及物化时冻结的本地金额报价）、4 个加密货币选项 及**可扫描的二维码**（`qr_payload` + `qr_png_base64`；BTC 用 BIP-21， TRON/ETH 代币用原始地址 —— Trust Wallet、MetaMask、Binance 等外部钱包 可直接识别），以及商户的 **CBPay 二维码 + 别名**，用 App 扫码即刻付款 （深链 `cbpay:pay?to=…&checkout=…`；`POST /v1/transfers` 接受 `checkout_token` 并在服务端校验应付额）。每笔付款入账时**自动兑换**为 `settlement_asset`（相同资产则不兑换）；`/state` 可见 `conversion_status`。新增公开端点 `GET {checkout_url}/quote`，返回国家 目录、加密货币应付额与 CBPay 应付额。新增错误 `country_required`、 `country_unavailable`、`settlement_asset_disabled` 与 `checkout_amount_mismatch`。详见 [收款指南](/zh/guides/payins#通用收款链接checkout)。 **新增** * **主动收款失败的拒绝详情**：当主动收款（`collect`，C2P 或即时扣款） 变为 `failed` 时，payin 现在包含 `failure` 对象，说明拒绝来源 （`provider` = 付款人的银行，`core` = 扣款前校验）以及具体的代码和 消息——在 `POST` 的同步响应、`GET /v1/payins/{id}` 和 webhook 中均可 见。此前仅暴露通用的 `failed` 状态。详见 [payins 指南](/zh/guides/payins)。 **新增** * **通用收款链接（`checkout`）**：`POST /v1/payins` 接受 `method: "checkout"` 并返回 `checkout_url` —— 一个带品牌的公开页面， 付款人自行选择支付方式：QR、银行卡、银行转账或**加密货币**（TRON 上的 USDT、以太坊上的 USDT/USDC 以及 BTC），并为该笔收款生成专属充值地址， 支持部分支付累加。一个链接 = 一笔收款：最先完成支付的方式生效。状态可 通过 `GET {checkout_url}/state` 免认证查询；加密支付的 `payin_credited` 事件附带 `settled_via` 和 `crypto_amount`。支持 `success_url`、 `failure_url`、`expires_in`（10 分钟到 7 天）与幂等（重试返回同一链接）。 新增错误 `already_paid`、`checkout_expired` 与 `method_unavailable`。 详见[收款指南](/zh/guides/payins#通用收款链接checkout)。 **变更** * **卡支付捕获前认证过滤器**：只有当 3-D Secure 验证以认证成功或已尝试 结束、且认证数据完整时，卡扣款才会发送给处理方；未经真实认证的尝试会在 资金移动前被拒绝，付款人可以重试。支付页面还延长了设备数据收集时间 （约 11 秒）以提高发卡行的批准率。在测试环境中，金额以 `.44` 结尾可 模拟被该过滤器拒绝的尝试（完整表格见 [测试环境](/zh/environment-testing)）。 **新增** * **payin 银行卡支付（`card`）**：`POST /v1/payins` 接受 `method: "card"`（玻利维亚，BOB 或 USD）并返回 `payment_url` — 一个带有你组织品牌的托管支付页面，付款人在安全字段中输入银行卡并完成其 银行的 3-D Secure 验证。可选字段 `customer`、`success_url`、 `failure_url` 与 `expires_at`。支付确认通过 `payin_received` webhook 送达并像任何 payin 一样入账；若无人支付，`payin_expired` 会关闭该收款。 详见[payin 指南](/zh/guides/payins)。 **新增** * **swaps 与地址筛查响应中的 `account_id`**：`POST/GET /v1/swaps` 与 `POST/GET /v1/screenings/addresses` 的响应现在包含 `account_id` （操作所属的账户）。对单账户集成仅作参考；管理视图用它来归属每条记录。 **新增** * **比特币链上通道（`btc`/`btc`）**：crypto 产品支持的第四条网络。 每个账户现在出生即拥有**四个充值钱包**（新增比特币，bech32 地址 `bc1q…`）；BTC 充值入账到 BTC 余额（约 30 分钟确认，3 个区块）， 链上提现接受 `chain: "btc"`（支持 bech32、taproot 与 legacy 目标 地址；网络费由操作承担——收款方收到精确金额）。 [隔离钱包](/zh/guides/segregated-wallets)同样支持 `btc`/`btc` 组合（没有 gas：费用从钱包余额中扣除）。Travel Rule 与其他网络 一致，按 USD 估值。详见 [crypto 指南](/zh/guides/crypto)。 **变更** * **两步登录同样遵循手机号绑定冷却期**：登录 2FA 为 SMS/WhatsApp 且 号码为最近绑定且未验证时，登录验证码会通过更强的因素发出（身份 验证器应用，其次登录邮箱），而不是发送到该手机号——登录响应中会 返回实际使用的 `channel`。没有替代因素时，登录返回 `403 phone_binding_cooldown`，直到冷却期结束。验证码绝不会发送到 从当前会话绑定的号码。详见[安全与 2FA 指南](/zh/security-2fa)。 **变更** * **手机号处于冷却期时，OTP 质询自动改用更强的因素**：手机号为最近 绑定（24 小时冷却期）时，`POST /v1/otp/challenges` 在您已注册身份 验证器应用或已验证邮箱的情况下不再阻止 — 质询会自动通过该渠道发出 （层级 totp > email），响应中会返回实际使用的渠道。 `403 phone_binding_cooldown` 仅在没有任何替代因素时返回。此前， 即使拥有更强的因素，冷却期也会阻止所有 2FA 放宽操作（甚至包括停用 email 渠道）。详见[安全与 2FA 指南](/zh/security-2fa)。 **新增** * **已验证身份成为档案数据的最终来源**：KYC/KYB 入驻获批后， `display_name`（个人 = 名 + 姓；企业 = 法定名称）、`tax_id` 和 `country` 会自动由已验证的身份回填。详见 [KYC 指南](/zh/guides/kyc) 与[档案指南](/zh/guides/profile)。 **变更** * **`PATCH /v1/me` 在验证获批后锁定身份字段**：当 `kyc_status: approved` 时，修改 `display_name`、`tax_id` 或 `country` 将返回 `409 identity_locked`（[错误页](/zh/errors)新增该代码）。 `phone` 仍可通过其专属验证流程修改。 **新增** * **AML 筛查 PDF 报告**： `GET /v1/aml/screenings/{screeningID}/report` 可将历史记录中的任一筛查 下载为带你品牌的高管级 PDF 报告 —— 封面呈现决策及其风险信号灯、风险 指标（制裁、观察名单、PEP、负面媒体等）、合并匹配、别名、术语表，以及 列明所查国际数据源的最终背书章节。通过 `lang=en|es|zh` 支持三语 （默认英文）。纯读取，无费用。详见 [AML 指南](/zh/guides/aml#筛查-pdf-报告) 的新章节。 * **新错误码 `invalid_language`**（HTTP 400）：PDF 报告的 `lang` 不是 `en`、`es` 或 `zh`。详见[错误页面](/zh/errors)。 **修复** * **AML 筛查的企业字段**：示例与 spec 曾将 `tax_id`/`registration_number`/`country_of_incorporation` 记为 `customer.company` 的扁平字段，但筛查引擎会以 `422` 拒绝。标识符应放在 `registration_authority_identification`，国家放在 `place_of_registration`，`incorporation_date` 为 `{year, month, day}` 对象。指南与 spec 已修正（已在生产环境验证）。 **新增** * **新走廊：厄瓜多尔（USD）**，支持四种出金方式 —— `bank_transfer` （银行转账）、`deuna`（DeUna 钱包）、`cash_pickup`（柜台取现，无需 账户）和 `cnb`（非银行代理点）。收款人支持结构化姓名 （`given_name`/`first_surname`/...）或从 `name` 自动拆分，并可附带 可选的汇款人信息块（`sender_name` 或其结构化字段）。各方式示例见 [出金指南](/zh/guides/payouts)与 API 规范。 * **新错误码 `channel_unavailable`**（HTTP 503）：该走廊的支付通道 暂时不可用。请稍后使用相同的 `idempotency_key` 重试。详见 [错误页面](/zh/errors)。 **新增** * **测试账户生而带有数据**:测试环境的每个新账户都自带约 6 个月的 真实感演示历史,覆盖所有产品(payouts、payins、转账、加密、兑换、 卡片、banking、联系人……),余额、对账单和分析报表开箱即用。适用于 所有创建路径(注册、社交登录、管理员创建及控制台的 test/live 开关)。 **变更** * **环境完全独立**:测试数据不再从生产快照刷新 —— 两个环境之间不复制 任何内容。已更新[环境与测试](/zh/environment-testing)指南。 **新增** * **官方 MCP 服务器**上线 `https://mcp.cbpayapp.com`:将你的 AI 编辑器或 助手(Cursor、VS Code、Claude、ChatGPT 及任何 MCP 客户端)连接到本文档 —— 搜索、带真实示例的端点与错误目录,无需离开编辑器。只读、无需身份 验证。新增 [MCP 服务器](/zh/mcp)页面,支持一键安装与按客户端配置。 **变更** * **测试环境**:新账户现在生而带有 `kyc_status: approved` —— 您可以 立即演练所有产品,没有入驻闸门。适用于所有创建路径(注册、社交 登录、管理员创建以及控制台的 test/live 切换);现有测试账户已追溯 批准。**live** 环境不变:账户生而未验证,资金转出前 KYC/KYB 仍为 强制要求。要在测试模式演练验证流程,请使用第三方 KYC/KYB 验证。 **变更** * `PUT /v1/otp/preferences`:通过电话渠道(`sms`/`whatsapp`)为 `login` 操作启用 2FA 时,现在要求账户电话号码已**验证**(先完成任意 SMS/WhatsApp OTP 挑战)。号码未验证时 API 返回 `409 phone_verification_required`。该保障可防止输错的号码在启用登录 2FA 时把你锁在账户外。 **修复** * `POST /v1/me/passkeys/register/begin` 与 `DELETE /v1/me/passkeys/{passkeyID}` 现在接受不带请求体的请求,与规范 文档一致(请求体可选)。此前会返回 `400 invalid_json`。有密码的账户仍 必须提供当前密码(缺失或错误时返回 `403 invalid_password`);仅使用 社交登录的账户凭其会话即可通过。 **修复** * `POST /v1/me/totp/enroll` 现在接受不带请求体的请求,与规范文档一致 (请求体可选)。此前会返回 `400 invalid_json`。有密码的账户仍必须提供 当前密码(缺失或错误时返回 `403 invalid_password`);仅使用社交登录的 账户凭其会话即可通过。 * `PUT /v1/otp/preferences` 选择 `email` 或 `totp` 渠道时返回 500 错误; 已修复 — 四个渠道(`sms`、`whatsapp`、`email`、`totp`)均可正常保存。 **变更** * PDF 对账单:操作状态现在以颜色区分(绿色已完成、琥珀色待处理、红色 失败),便于快速浏览。 **新增 — 列表支持 CSV / Excel 导出** * `movements`、`payouts`、`payins` 与 `transfers` 列表现在接受 `format=csv` 或 `format=xlsx` 参数，将行数据下载为可直接用于会计的 文件（每次下载最多 10,000 行；`from`/`to`、`status` 等过滤器同样 生效）。 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -o movements.xlsx "https://api.qbank.cl/platform/v1/movements?from=2026-07-01&to=2026-07-13&format=xlsx" \ -H "Authorization: Bearer pk_…" ``` * 不带 `format` 时响应仍是常规的分页 JSON —— 无兼容性变更。 **Breaking — 隔离钱包迁移至 `/v1/segregated-wallets`** * 所有隔离钱包路由从 `/v1/wallets*` 重命名为 `/v1/segregated-wallets*`。 方法、参数、响应结构、费用和 webhook 均不变——只有路径前缀改变。 **没有兼容别名**：旧的 `/v1/wallets*` 路由现在返回 `404`。 * 映射（15 条路由遵循同一模式）： | 之前 | 现在 | | ---------------------------------------------------------------- | ----------------------------------------------------------------------- | | `POST/GET /v1/wallets` | `POST/GET /v1/segregated-wallets` | | `POST /v1/wallets/import` | `POST /v1/segregated-wallets/import` | | `GET /v1/wallets/{id}`（+ `/balance`、`/deposits`、`/transactions`） | `GET /v1/segregated-wallets/{id}`（+ 相同子路由） | | `POST/GET /v1/wallets/{id}/sends`（+ `/{sendID}`、`/receipt`） | `POST/GET /v1/segregated-wallets/{id}/sends`（+ 相同子路由） | | `GET /v1/wallets/{id}/deposits/{depositID}/receipt` | `GET /v1/segregated-wallets/{id}/deposits/{depositID}/receipt` | | `POST /v1/wallets/{id}/export` · `GET/POST .../auto-forward` | `POST /v1/segregated-wallets/{id}/export` · `GET/POST .../auto-forward` | * 钱包发送/入金的响应、webhook 和回执邮件中的 `receipt_url` 现在指向 新路径。 * 原因：通用前缀 `/v1/wallets` 经常与 [crypto](/zh/guides/crypto) 产品的 **充值钱包**混淆。充值钱包不受影响，仍位于 `/v1/crypto/wallets`。 **新增 — 每个钱包响应带有 `type` 鉴别字段** * 充值钱包（`/v1/crypto/wallets`）现在包含 `type: "deposit"` 和 `receive_only: true`。 * 隔离钱包包含 `type: "segregated"`。 * 请用它防御性地区分两个产品——不要只依赖路由。 **新增 — `payin_expired` webhook：未支付代收的自动关闭** * 当一笔待支付的代收（二维码或托管 checkout）在未收到付款的情况下过期或 失败时，payin 现在会自动从 `pending` 变为 `expired`（或 `failed`）—— 此前可能会无限期停留在 pending。 * 新增 **`payin_expired`** webhook 事件，携带 `payin_id`、最终状态、 通道和参考号，让您无需轮询即可在自己的系统中关闭该笔代收。可通过 `POST /v1/webhooks/subscriptions` 订阅。 * 任何情况下都不产生资金变动：如需重新收款，请创建新的 payin。 **变更 — 凭证、对账单与邮件全新设计** * 所有 PDF 凭证（`GET .../receipt`）升级为银行级设计：带 logo 与凭证编号的页眉、 产品图标、突出显示的金额、双栏明细、带二维码的"可验证文档"区块，以及机构化页脚。 品牌符号以水印形式淡淡呈现；未完成的操作仍保留状态水印。 * 对账单 PDF（`GET /v1/reports/statement?format=pdf`）新增带图标的汇总卡片、 对账已验证徽章及各分区图标；Excel 导出结构不变。 * 邮件（凭证、验证码与安全通知）现共用带有贵组织机构化页眉与页脚的品牌模板。 * 法币转出凭证中的收款银行始终按名称显示：若操作以目录中的 `bank_code` 创建， 会自动解析为银行名称。 * API 无变化：路由与响应结构不变，仅文档与邮件的外观更新。 **新增 — 用户会话的刷新令牌（refresh tokens）** * 每次登录（密码、OTP、社交登录、通行密钥、handoff 和注册）现在会在 24 小时 `access_token` 之外一并返回一次性 **`refresh_token`**（`rt_…`）， 用于免重新登录续期会话：`POST /v1/auth/refresh` 签发新的令牌对并轮换 刷新令牌（每次轮换有效 30 天，自最初登录起绝对上限 90 天）。详情与 安全规则见[身份认证 → 会话续期](/zh/authentication#session-renewal-refresh-tokens)。 * **严格轮换与防盗检测**：交换时会吊销该设备之前的 access token；提交 已被交换过的刷新令牌会吊销整条令牌链，并在 `GET /v1/me/security/events` 中记录 `refresh_token_reuse` 事件。退出 登录、吊销会话或修改密码也会使刷新令牌失效。 * 新错误码：`401 invalid_refresh_token`。API key（`pk_`）不受影响： 永不过期，也不使用刷新机制。 **新增 — 使用模拟资金的测试环境（沙盒）** * 新的 **test** 环境：`https://cryptobank.qbank.cl/platform`。API 完全 相同，所有通道由确定性的内部模拟器提供服务 —— 始终可用，不依赖任何 第三方。操作在几秒内自动完成，**魔法值**（`.99`/`.77` 金额、 `REJECT` 收款人、OTP `000000` 等）可强制触发其他所有结果。完整指南见 [环境与测试](/zh/environment-testing)。 * **按环境区分的 API 密钥**：test 只签发和接受 `pk_test_` 密钥；live 只接受 `pk_`。另一环境的密钥返回 `401` —— 不可能误用错环境。 * 每个响应都带有 **`CBPay-Environment`** 头（`test` | `live`）， `GET /healthz` 返回 `livemode`。 * **一键 test/live 切换**：`POST /v1/auth/environment-handoff`（live） 签发一次性 60 秒令牌，在 `POST /v1/auth/handoff`（test）兑换为测试 环境会话，并自动创建镜像账户。 **新增 — AML 筛查审计历史** * `GET /v1/aml/screenings` 与 `GET /v1/aml/screenings/{screeningID}` 列出并查询 本地保存的每条 AML 筛查（个人、企业及重新筛查）——主体、风险、费用与完整结果。 * `POST /v1/aml/screenings` 与 `POST /v1/aml/rescreen` 现须 `idempotency_key` （操作收费）。相同键重放返回原记录且 `idempotency_hit: true`，不会重复扣费。 * `PATCH /v1/aml/monitoring` 将每次启用/停用写入同一历史（`kind: monitoring`）； 状态实际变更时须提供 `idempotency_key`（启用会收费）。 **新增 — 链上提现的 Travel Rule（FATF R.16）** * 超过配置阈值（默认 1,000 USD）的加密货币提现，现在必须在资金移动前 申报受益人：自有钱包用 `wallet_type: "self_hosted"` + `beneficiary_name`；目的地在其他机构时用 `travel_address` + `beneficiary_name`（数据交换内联完成，付款地址由收款机构提供）。 低于阈值一切不变。 * 提现响应新增 `travel_rule_status` （`not_required` / `self_hosted_attested` / `approved`）。 * 新增错误码：`travel_rule_required`、 `travel_rule_beneficiary_required`、`travel_rule_address_mismatch`、 `travel_rule_rejected`、`travel_rule_pending`、 `travel_rule_incomplete_approval`、`travel_rule_unavailable`。详见 [加密货币指南](/zh/guides/crypto)与[错误页](/zh/errors)。 **新增 — 余额历史中的银行序列** * `GET /v1/balances/history` 的 `assets` 现在包含银行账户 （`BANK_USD`、`BANK_EUR`）的每日序列，各以自身货币（2 位小数）呈现， 可作为 USDT/USDC/BTC/GOLD 旁的又一筛选项直接绘图。它们仍不计入 `total_usd` 聚合——该聚合仅覆盖运营余额。 [分析](/zh/guides/analytics)指南已更新。 **新增 — 付款与收款列表的国家筛选** * `GET /v1/payouts` 和 `GET /v1/payins` 支持 `country` 筛选 （ISO 3166-1 alpha-2，例如 `?country=MX`），可与 `status`、 `from`/`to` 及分页组合使用。[付款](/zh/guides/payouts)与 [收款](/zh/guides/payins)指南已更新。 * `GET /v1/rates` 的 `fees` 块现在返回**有效**费用配置（组织默认值已与账户覆盖项解析合并）。 此前无覆盖项的账户会看到 `fees: []`；请用此块在创建操作前报价确切费用。 **变更 — 按账户类型的钱包限额** * **充值钱包**：每个账户——个人和企业——每个受支持组合（`tron`/`usdt`、 `eth`/`usdt`、`eth`/`usdc`）都恰好持有**一个充值钱包**，注册时自动免费 开通。`POST /v1/crypto/wallets` 现在仅用于补齐缺失的组合；组合已存在时 对所有账户类型都返回 `422 wallet_limit_reached`（此前企业可创建更多）。 * **隔离钱包**：现在个人账户也可使用，每个网络+资产组合限 **1 个** （第二次尝试返回 `422 wallet_limit_reached`）。企业账户仍不限数量。 `403 company_required` 错误不再适用于隔离钱包。 * [加密货币](/zh/guides/crypto)与[隔离钱包](/zh/guides/segregated-wallets) 指南、[个人与企业](/zh/concepts/persons-companies)页面及 [错误](/zh/errors)页面已更新。 **新增 — 持续交易监控（合规控制）** * 平台现已通过银行级合规控制实时监控每一笔操作。对绝大多数客户而言这是 无感的：不改变任何流程，也不会增加可感知的延迟。 * 新增错误码已记录在[错误](/zh/errors)页面：`403 compliance_hold` （操作被合规拦截）、`403 geo_restricted`（不支持的司法辖区）和 `503 compliance_check_unavailable`（合规检查暂时不可用 — 操作未发出； 请使用相同的幂等键重试）。 **新增 — 文档支持 3 种语言（默认英语）** * 本文档现已完整提供**英语**（默认语言）、**西班牙语**和**简体中文** 三个版本。可通过站点顶部的语言选择器切换语言。 * API Reference 同样提供三种语言版本（端点与示例完全一致，仅描述文字 不同）。 * Postman 集合与编译版 Markdown 指南在任意语言版本下都保持最新。 **新增 — 钱包筛查（区块链地址的 AML 风险）** * 新产品：`POST /v1/screenings/addresses` 依据全球链上情报（制裁名单、 非法资金暴露等）评估任意区块链地址，并返回 `Low`/`Medium`/`High`/`Severe` 风险等级及完整证据。每次扫描收取固定 费用（`address_screening`，失败时自动退款），且必须携带幂等键。历史 记录可通过 `GET /v1/screenings/addresses`（+`/{id}`）查询。 * **免费的自动保护**：链上提现在签名前会先评估目标地址（严重风险 ⇒ 拒绝并全额退款）；入账存款在入账前会先评估发送方（严重 ⇒ 暂扣待 合规审核；高风险 ⇒ 入账并附带警报）。 * 新增 webhook：`crypto_deposit_held` 和 `crypto_deposit_alert`。 * 新增指南：[钱包筛查](/zh/guides/screenings)。 **新增 — 通过 CDN 提供的公开资源（头像、品牌素材、收款二维码）** * **CDN 头像**：`avatar_url`（出现在 `PUT /v1/me/avatar`、 `GET /v1/resolve` 和联系人接口中）现在是一个**绝对公开 URL**，图片 发布到 CDN 后无需认证即可加载；`GET /v1/avatars/{accountID}` 以 `302` 重定向到该 URL（旧版头像仍然直接返回）。 * **品牌素材 URL**：`GET /v1/branding` 新增 `logo_url` 和 `symbol_url` —— 指向 Logo 的公开 CDN URL，前端无需解码 base64 即可套用主题 （`*_png_base64` 字段依然保留）。 * **收款二维码（Payin QR）**：QR 收款（`POST /v1/payins`，method 为 `qr`）新增 `qr_image_url`，即发布到 CDN 的二维码 PNG，与原有的 base64 `qr_image` 并存。直接放进 `` 标签即可。 不会破坏任何现有集成：所有既有字段均保留；这些 URL 都是新增的。 指南：[个人资料](/zh/guides/profile) 与 [收款](/zh/guides/payins)。 **新增 — 合规目录** * 新增 `GET /v1/aml/catalogs`：构建合规与验证表单所需的全部目录 （性别、各国法律实体形式、收入/财富来源、行业标准、ISO-3166 国家 与行政区划）。这些数据此前无法通过 API 获取。 **变更** * `GET /v1/rates` 与 `GET /v1/rates/history` 的 `asset_prices` 区块 不再包含内部字段 `source`；请使用 `settlement_grade` 和 `updated_at` 来判断价格是否可执行以及其新鲜程度。 指南：[AML 筛查](/zh/guides/aml)。 **新增 — 每个账户自创建起即拥有其充值钱包** * 账户创建时（个人或企业），系统会自动且**免费**开通其三个加密充值 钱包：`tron`/`usdt`、`eth`/`usdt` 和 `eth`/`usdc`。注册完成后， `GET /v1/crypto/wallets` 即可返回这三个地址（开通在后台进行；在 注册的当秒查询可能需要稍等片刻）。 * `POST /v1/crypto/wallets` 现在用于创建**额外**的钱包（企业账户）； 个人账户自注册起已占用每种组合的名额。此变更之前创建的账户已补齐 缺失的钱包。 **变更** * 公开账户注册现在按 IP 限流（`429 too_many_attempts`）。 指南：[加密货币](/zh/guides/crypto)。 **新增 — 完整可追溯性：对账单中的银行业务、费用明细拆分与钱包托管** * **更丰富的对账单**：新增 `card_transactions`（卡消费）、`swaps` （余额兑换）和 `banking_operations` 区块。如果你使用 Banking，你的 银行账户会以 `BANK_USD`/`BANK_EUR` 镜像余额的形式在 `assets` 区块 中对账。 * **费用明细拆分**：payout、payin 和加密提现现在将费用拆分为 `fee_percent` 和 `fee_fixed`（两者相加恰好等于 `fee`）；独立收费 项带有 `fee_model: "fixed"`，并在 PDF/Excel 中标注为 **Fixed Com**。 * **新增回执**：`GET /v1/banking/operations/{id}/receipt`、 `GET /v1/wallets/{walletID}/sends/{sendID}/receipt` 和 `GET /v1/wallets/{walletID}/deposits/{depositID}/receipt`。 `banking_operation_status_changed` webhook 现在包含 `receipt_url`。 * **独立钱包托管**：每个钱包新增 `custody` 字段（`cbpay` | `client`）； 平台会同步完整的链上活动，并发送 `wallet_external_movement` webhook （在平台之外签名的转账，`client` 托管下属于预期行为）以及 `wallet_key_compromise_suspected`（严重警报）。 * **分析（Analytics）**：新增 `sections.banking.volume`（经由你的银行 账户流转的资金，同时计入 `gross_volume`）、 `sections.verifications.fees_by_kind`（KYC 与 KYB 支出分开统计）、 `sections.adjustments` 和 `deposits.wallet_fees_usd`。 * **按钱包保证的账务**（`cbpay` 托管）：对账单中的全生命周期对账， 以及每笔发送详情中的 `funding_sources`（充值→发送的 FIFO 归因）。 `BANK_*` 镜像余额也会出现在 `GET /v1/balances` 中，并带有 `custody: "banking"`。 指南：[对账单](/zh/guides/statement)、[银行业务](/zh/guides/banking)、 [独立钱包](/zh/guides/segregated-wallets)、 [回执](/zh/guides/receipts) 与 [分析](/zh/guides/analytics)。 **新增 — 面向仪表盘的历史序列** * **`GET /v1/rates/history`**：你账户汇率的演变（每个数据点均含 payout 和 payin 两侧），支持 `day` 或 `hour` 粒度，并为每种货币 提供带符号的 `change_pct` —— 可直接用于带 "+3.4% / −3.0%" 徽章的 汇率图表。还包含 BTC 和 GOLD 的美元参考序列。 * **`GET /v1/balances/history`**：你余额的每日演变 —— 每种资产一条 序列，包含每日收盘余额（无缺口）、按每日历史价格估值的美元汇总 序列、期间的流入/流出以及当前快照 —— 带图表的余额卡片所需的一切。 * 汇率历史以约 90 天的每日汇率回填起步，此后持续记录。 完整示例见 [分析](/zh/guides/analytics)。 **新增 — 带真实性验证的 PDF 回执** * 每个交易类产品都有其**品牌化 PDF 回执**：payout、payin、内部转账、 加密提现与充值（`GET /v1/crypto/transactions` 中新增 `deposit_id`）、 swap 及卡消费均支持 `GET .../receipt`。语言参数 `?lang=es|en`。 * 这些产品的每个响应以及最终状态的 webhook 中均包含 **`receipt_url`**： 前端永远无需手动拼接 URL。 * **公开真实性验证**：每份 PDF 都带有签名代码和二维码，扫码打开 `GET /verify/receipts/{code}`（无需凭证）—— 对 API 返回 JSON，对 浏览器返回品牌化网页，始终显示**真实、当前**的状态与金额，绝不 展示收款人的个人数据。 * **未完成**操作的回执带有对角线水印（"PROCESSING" / "FAILED"）： 处理中的 PDF 永远不可能被冒充为付款凭证。 * 操作到达最终状态时**自动发送邮件**并附上 PDF，可按账户退订 （`PATCH /v1/me`，设置 `receipt_emails: false`）。 **新增 — 品牌** * `GET /v1/branding`：平台的生效品牌（Logo、颜色、名称），白标前端 可直接通过 API 套用主题。 **变更** * PDF [对账单](/zh/guides/statement) 现在使用品牌的**真实 Logo** 与 Inter 字体渲染（此前为文字字标），Excel 也在汇总表中加入了 Logo。 完整指南见 [回执](/zh/guides/receipts)。 **新增 — 独立钱包（仅限企业账户）** * 拥有**独立余额**（不在总账内）的链上钱包：创建 （`POST /v1/wallets`）、列表与详情，**导入**带私钥的外部钱包 （`POST /v1/wallets/import`），**导出**私钥 （`POST /v1/wallets/{id}/export`，共享托管），以及直接从钱包 **发送**加密货币（`POST /v1/wallets/{id}/sends`）。 * 实时链上查询：`GET .../balance`（含 gas）、`.../deposits` 和 `.../transactions`；可配置的**自动归集（auto-forward）** （`GET`/`POST .../auto-forward`）。 * 发送所需的 **gas** 由客户承担：没有 gas 时发送返回 `422 insufficient_gas`。导入与导出要求已登录的用户会话并开启 2FA。 * 新增费用：`wallet_import`、`wallet_export`、`wallet_send`。 * 新增 webhook：`wallet_deposit_received`、`wallet_send_status_changed`、 `wallet_key_exported`。新增服务开关：`wallets`。 * [对账单](/zh/guides/statement) 与 [仪表盘](/zh/guides/analytics) 均包含独立钱包区块。 完整指南见 [独立钱包](/zh/guides/segregated-wallets)。 **新增 — 账户资料、凭证与安全** * **密码**：自助修改（`POST /v1/me/password`，会吊销其他所有会话） 以及基于验证码的找回（`POST /v1/auth/password/forgot` → `POST /v1/auth/password/reset`），通过邮箱或已验证的手机号。forgot 始终返回 200（绝不泄露账户是否存在）。 * **登录邮箱**：经验证的变更（`POST /v1/me/email/change` → `confirm`， 验证码发送到**新**邮箱）以及当前邮箱的验证 （`POST /v1/me/email/verify`）。 * **永久别名**（`PUT /v1/me/alias`）与**个人资料二维码** （`GET /v1/me/qr`）：用于标识你的账户以**接收**转账。转账接受 `to_alias` 和 `to_qr_token`；`GET /v1/resolve` 可在发送前预览 收款人。 * **头像**：`PUT`/`DELETE /v1/me/avatar` 与 `GET /v1/avatars/{id}`。 * **自助 2FA**（`GET`/`PUT /v1/otp/preferences`）：按操作启用并选择 渠道 —— 除 SMS/WhatsApp 之外，现在还支持**邮箱**和**验证器应用 （TOTP）**。加强安全不受限制；降低安全等级需要验证。 * **验证器应用（TOTP）**：`POST /v1/me/totp/enroll`（二维码）→ `confirm`（返回 10 个一次性备份码）、`DELETE`，以及 `POST /v1/me/totp/recovery-codes` 用于重新生成备份码。 * **通行密钥（Passkeys / WebAuthn）**：使用设备生物识别（Face ID、 Touch ID、Windows Hello、安全密钥）的免密码登录。注册 （`/v1/me/passkeys/register/begin|finish`）、管理（`GET`、`DELETE`） 与登录（`/v1/auth/passkey/login/begin|finish`）。 * **会话与活动**：`GET /v1/me/sessions` + 吊销单个或全部会话，以及 `GET /v1/me/security/events`（账户安全历史）。 * 敏感事件（密码或邮箱变更、验证因子的添加/移除）会发送邮件提醒。 **新增 — 可复用的已验证身份（统一的 KYC/KYB）** * 客户已通过的 KYC/KYB 验证成为其在 CBPay 内的**唯一身份**：其数据 与文件可在其他产品中复用，无需重复填写或重复上传。指南： [可复用身份](/zh/guides/kyc#one-verification-for-everything-reusable-identity)。 * **卡片**：你账户的首次发卡会**从你已通过的验证中**自动填充持卡人 身份与文件 —— 你只需发送 `occupation` 和 `salary_usd`。显式提供的 字段仍然优先。 * **合规报告（KYB）**：`GET /v1/kyb/submissions/{id}/report` 下载 该验证的签名合规报告（PDF）。 **变更 — Breaking** * **`POST /v1/banking/third-parties`** 现在要求第三方**已通过**验证 的 `verification_id`。`type` 由验证类型推导（KYC ⇒ INDIVIDUAL， KYB ⇒ COMPANY），身份自动填充，已验证的文件会重新交付给银行服务 （`documents_synced`）。现有第三方继续正常运作。 * 面向指定人员（企业账户）的 **`POST /v1/cards`** 现在要求该人员 **已通过** KYC 的 `cardholder.verification_id`；其身份与文件来自 该验证。 * 新增错误：`422 verification_required`、 `422 verification_not_approved`、`422 verification_kind_mismatch`、 `422 verification_invalid`。 **新增 — 账户汇总（分析）+ 第三方银行用户** * **`GET /v1/analytics/summary`**：一次调用即可获取构建仪表盘所需 的账户全部序列与统计 —— 按周期（日/周/月，含与上一周期的对比）的 总量（流入/流出）、交易数与新用户数，按国家的全局视图，以及 每个服务（payouts、payins、充值、提现、内部转账、swaps、卡片、 banking、KYC/KYB、AML、联系人）各自的区块及其维度（国家、货币、 方式、状态、链、商户）。另有 `spending`（你在各服务上消耗的费用） 与按美元估值的 `balances`。新增指南： [你的账户汇总](/zh/guides/analytics)。 * **第三方银行用户（仅限企业）**：`POST/GET /v1/banking/third-parties`（+文件、提交、账户、余额），可将你的 终端客户注册为独立的银行用户，拥有自己的身份/KYC 及以其名义开立 的账户。按账户隔离。 * **新限制**：个人账户最多只能持有 1 个银行账户 （`409 banking_account_limit`）。 **变更 — 玻利维亚与委内瑞拉汇率** * `GET /v1/rates` 中的 USD→BOB 与 USD→VES 汇率现在反映我们实际用于 处理你付款的市场（此前发布的参考汇率与实际应用值不符）。 * 若其中某一汇率暂时不可用，该国家会从 `GET /v1/rates` 中省略，且 该货币的操作返回 `422 currency_not_supported`，直至恢复 —— 我们 绝不使用错误的汇率报价。建议在以 `BOB` 或 `VES` 报价前查询 `GET /v1/rates`（或订阅汇率 webhook）。 **新增 — Swap：在你的余额之间兑换** * 新产品 `swaps`：在 `USDT`、`USDC`、`BTC` 和 `GOLD` 之间即时兑换， 资金不离开你的账户 —— 支持任意币对，包括 `BTC` ↔ `GOLD` 直接兑换。 `POST /v1/swaps`（同步，带 `idempotency_key`）、 `GET /v1/swaps/quote`（免费指示性报价）以及 `GET /v1/swaps` （+`/{id}`）查询历史。 * 报价即你账户的执行汇率：报价 = 到账，无额外费用。BTC/GOLD 采用 实时价格（价格不够新鲜时 swap 会以 `503 pricing_unavailable` 被拒绝）。 * 涉及 BTC/GOLD 的兑换与 payout 及卡消费共享单笔与 24 小时交易量 限额（`GET /v1/settlement`）。新增指南：[Swaps](/zh/guides/swaps)。 **新增 — 联系人与按手机号发送** * **联系人簿**（`/v1/contacts`）：完整 CRUD，支持搜索与收藏。每次 发送（内部转账、payout、加密提现）都会**自动将其目标保存为 联系人** —— 自动去重；可通过 `"save_contact": false` 关闭。 * **手机通讯录导入**（`POST /v1/contacts/import`，每次最多 1,000 条）：将手机号规范化为 E.164，并告知哪些联系人**已拥有 CBPay** （`has_cbpay`，仅在你的运营方范围内匹配）。 * **按手机号转账**：`POST /v1/transfers` 接受 `to_phone`（仅限手机 号已通过 **OTP 验证**的账户；存在歧义时返回 `422 recipient_ambiguous`）以及 `to_contact_id`。 * **快捷发送给联系人**：payout 支持 `beneficiary_contact_id`（使用 联系人已保存的收款人信息），加密提现支持 `to_contact_id`（使用其 已保存的地址）。新增指南：[联系人](/zh/guides/contacts)。 **新增 — KYC/KYB 身份验证（托管向导、OCR 文件与视频活体检测）** * **强制入驻**：每个新账户在运营前必须通过其身份验证（个人 ⇒ KYC， 企业 ⇒ KYB）。在此之前只能**入金**（payins、加密充值、入账转账） 和读取；其余操作均返回 `403 verification_required`。通过 `POST /v1/me/verification/link` 获取你的链接，并用 `GET /v1/me/verification` 查询状态 —— 通过后你的 `kyc_status` 会自动更新。现有账户已被豁免并标记为通过。 * **第三方验证（仅限企业账户）**：生成托管链接 （`POST /v1/kyc/links`、`POST /v1/kyb/links`）或通过 API 提交数据 （`POST /v1/{kyc,kyb}/submissions`），使用 presign + OCR 上传文件， 并通过活体检测链接完成 liveness 校验。新增固定费用 `kyc_verification` / `kyb_verification`，在创建时计费（必须携带 `idempotency_key`，失败时自动退款）。 * 7 个新 webhook：`kyc/kyb_verification_status_changed`、 `kyc/kyb_link_completed`、`kyc/kyb_document_validated`、 `kyc_liveness_completed`。完整指南见 [KYC 与 KYB 验证](/zh/guides/kyc)。 **变更（BREAKING）— 名单筛查更名为 AML** * `POST /v1/kyc`、`POST /v1/kyc/rescreen` 和 `PATCH /v1/kyc/monitoring` 已被**移除**：名单筛查现位于 `POST /v1/aml/screenings`、 `POST /v1/aml/rescreen` 和 `PATCH /v1/aml/monitoring`（语义相同， 沿用相同的 `compliance_*` 费用）。错误码 `no_kyc` 变为 `no_screening`，且筛查不再影响你的 `kyc_status`。新增 `aml_screening_updated` webhook 及新的 `aml` 服务开关（`kyc` 开关 现在管控身份验证）。指南：[AML 筛查](/zh/guides/aml)。 **修复 — 多方式国家在不带 `method` 时的银行目录** * `GET /v1/payouts/banks?country=VE` 曾返回 `400` 要求提供 `method`， 而 `?country=BO` 返回 `400 payout_corridor_unsupported`。现在 **不带 `method` 的目录会返回该国家所有 payout 方式的银行并集** （按代码去重），与本文档的承诺一致；传入 `method` 则限定为单一 通道（该参数现已在参考文档中说明）。 **新增 — 使用 BTC 与 GOLD 进行卡消费（即时兑换）** * `spending_asset` 现在也接受 **BTC 和 GOLD**：消费按**每个事件发生 时刻的有效价格**兑换（与 `GET /v1/rates` 的 `settlement` 区块中的 价格一致）。 * **授权**：预留等值金额外加一小块缓冲（并非扣费；结算时返还）。 如果执行价格不可用，消费会以 `pricing_unavailable` 被拒绝 —— 你的余额绝不会以不可信的价格被兑换。 * **结算**：最终金额按扣款时刻的价格重新报价，缓冲的多余部分自动 返还。授权的**冲正**：原额返还，不做兑换。扣款后的**退款/调整**： 按事件时刻的价格重新兑换（价格波动由你的余额承担）。 * BTC/GOLD 消费与 payout 共享账户的波动性资产限额：单笔 （`settlement_limit_exceeded`）与 24 小时交易量 （`settlement_daily_limit_exceeded`）。 **新增 — 选择你的卡从哪个余额消费（USDT 或 USDC）** * 每张卡现在都有一个**消费资产**（`spending_asset`）：其消费从账户 的 USDT 或 USDC 余额扣款，与美元 1:1，且无兑换费用。默认 USDT （与历史行为完全一致）。 * 可在创建卡时设置（`POST /v1/cards` 中的 `spending_asset`），或 随时通过 `PATCH /v1/cards/{cardID}` 修改。修改仅对未来的消费生效： 处理中的授权仍保留（并退回到）其扣款时的资产。 * 卡交易现在暴露 `spend_asset` 和 `spend_amount`（实际扣款的余额与 金额）；`amount_usd` / `amount_usdt` 仍为美元参考值。单卡限额仍 以美元计量。 * 新增错误：`400 spending_asset_unavailable`（BTC/GOLD 不可用于卡 消费），以及当运营方停用该资产时授权被拒的 `spending_asset_disabled`。 **变更 — 多资产结算加固** * 使用 BTC/GOLD 的付款在单笔限额之外，新增**按账户滚动 24 小时 交易量上限**（`422 settlement_daily_limit_exceeded`）。它以 `volatile_daily_limit_usdt` 显示在 `GET /v1/settlement` 中。 * **卡片**费用（发卡、注销与月费）现在也从你的默认结算余额扣款， 与其他服务一致。卡**消费**仍以 USDT 结算。 **新增 — 用任意余额支付 payout 与服务费（多资产结算）** * payout 与服务费（KYC、钱包创建、banking）现在可以从**你的四个 余额中的任意一个**（USDT、USDC、BTC、GOLD）扣款。定价仍以 USDT 报价；总额按当时的有效结算价格换算为所选资产。详情见 [资金模型](/zh/concepts/money-model#choose-which-balance-pays)。 * 新增 `GET/PUT /v1/settlement`：设置你账户的**默认余额** （`default_settlement_asset`）。可在 `POST /v1/payouts` 及 QR confirm 中通过 `settlement_asset` 按单笔覆盖。 * payout 响应现在记录 `settlement_asset`、`settlement_amount` （实际扣款的准确金额 —— 也是失败时退款的金额，绝不重新报价） 和 `settlement_rate`。 * `GET /v1/rates` 新增 `settlement` 区块，包含每个已启用资产的有效 价格；`asset_prices` 现在携带 `source`、`updated_at` 和 `settlement_grade`（价格是否适合执行）。 * 新增错误：`503 pricing_unavailable`（BTC/GOLD 执行价格不可用）、 `400 settlement_asset_disabled`、`400 invalid_settlement_asset` 和 `422 settlement_limit_exceeded`（波动性资产的单笔限额）。 **变更 — 预告银行转账的短参考码** * `POST /v1/payins` 使用 `method: "bank_transfer"` 时现在返回一个 **12 位字母数字短 `reference`**（例如 `CBW4N8R2T6P9`），取代原来 的 UUID：银行的备注字段有硬性长度限制（巴拉圭/SIPAP 限制为 20 个 字符且不允许特殊字符），UUID 从来放不下。 * 自动匹配接受新参考码，**同时**继续接受旧预告中的 UUID —— 现有的 `pending` payin 不受影响。金额+货币的兜底匹配保持不变。 * `GET /v1/payins` 与详情接口在 payin 处于 `pending` 期间通过 `reference` 暴露预告参考码。 **新增 — 巴拉圭收款（预告银行转账）** * 新收款通道 `PY`/`PYG`/`bank_transfer`：通过 `POST /v1/payins` 预告存款，你的付款人转账（SIPAP 或收款银行的行内转账）并在备注中 填写 `reference`，款项按你的 `payin_rate` 自动以 USDT 入账，与 其他国家一致。指南见 [收款](/zh/guides/payins)。 * 瓜拉尼不使用小数：请预告**精确的整数金额**（例如 `"596000"`）。 金额+货币的兜底匹配照常适用。 * 该通道出现在 `GET /v1/payins/methods` 中，且 `delivery: polling`。 **新增 — 多币种虚拟余额（USDT、USDC、BTC、GOLD）** * 每个账户现在持有**四个独立的虚拟余额**：`USDT`（运营货币）、 `USDC`、`BTC`（8 位小数，聪）和 `GOLD`（足金克数，6 位小数， 托管方背书）。它们永不混合，也绝不自动兑换。详情见 [资金模型](/zh/concepts/money-model)。 * **`GET /v1/balances`** 始终返回全部四个余额（未使用该货币时为 零），`GET /v1/movements` 可用 `?asset=` 按货币筛选。 * **多币种内部转账**：`POST /v1/transfers` 接受 `asset`（默认 `USDT`，可选 `USDC`、`BTC`、`GOLD`）—— 始终在**同一货币**的余额 之间进行，无兑换、无费用。 * **链上 USDC**：创建 `eth`/`usdc` 钱包，通过以太坊充值与提现 USDC。每笔充值入账到其对应资产的余额。指南见 [加密货币](/zh/guides/crypto)。 * **参考价格**：`GET /v1/rates` 包含 `asset_prices`，提供各货币的 美元参考价（BTC 按单位、GOLD 按克）—— 仅用于估值，无兑换、无 点差。 * **多币种对账单**：新增 `assets` 区块，每个非 USDT 余额独立对账 （期初/流入/流出/期末及各自的 `balanced` 标志），PDF 与 Excel 导出中同样包含。 * payout、payin、卡片与服务费仍**仅针对 USDT 余额**运作。 **新增 — 社交登录（Google、Apple、Microsoft、Meta）** * 通过令牌交换实现 Google、Apple、Microsoft 与 Facebook 的**免密码 注册与登录**：你的前端使用提供方 SDK 获取凭证，并在 `POST /v1/auth/oauth` 兑换为 CBPay 会话。完整指南见 [社交登录](/zh/guides/social-login)。 * **新增端点**：`POST /v1/auth/oauth`（统一的登录 + 注册）、 `GET /v1/auth/oauth/providers`（已启用的提供方，公开）、 `GET/POST /v1/me/identities` 与 `DELETE /v1/me/identities/{provider}` （在会话中关联/解绑提供方）。 * **集成 2FA**：如果账户在登录时强制 OTP，社交登录同样返回 `otp_required` + `pending_token`。 * **多方式**：一个账户可同时拥有密码和多个提供方；仅当提供方返回 已验证邮箱时才会按邮箱自动关联。 * [目录](/zh/errors) 中的新错误码：`invalid_provider`、 `provider_not_configured`、`invalid_credential`、`email_conflict`、 `identity_taken`、`last_login_method`。 **修复** * Postman 页面的"集合已更新"标记现在能正确显示距上次更新的时间 （此前显示为空指示器）。 **新增 — 通过 SMS 与 WhatsApp 的 OTP/2FA** * **敏感操作的两步验证**：你的运营方可以要求在登录、payout、加密 提现、内部转账、banking 操作、卡片明文查看、签发 API key、添加 成员或更换手机号之前输入一次性验证码（通过 SMS 或 WhatsApp）。 完整指南见 [安全与 2FA](/zh/security-2fa)。 * **新增端点**：`POST /v1/otp/challenges`（发送验证码）、 `POST /v1/otp/challenges/{id}/verify`（返回用于 `X-OTP-Token` 请求头的一次性 `otp_token`）、`GET /v1/otp/challenges`（+ 详情） 以及 `GET /v1/otp/settings`（你的生效策略）。 * **两步登录**：在 `login` 上启用 OTP 后，`POST /v1/auth/login` 返回 `otp_required: true` + `pending_token`，会话在 `POST /v1/auth/login/otp` 签发。 * **仅限用户会话**：`pk_` API key 免除 —— 你的服务器间集成无需 任何改动。 * [目录](/zh/errors) 中的新错误码：`otp_required`、`otp_invalid`、 `phone_required`、`phone_binding_cooldown`、`too_many_attempts` 等。 **文档 — 个人 vs 企业与统一指南** * **新增 [个人与企业](/zh/concepts/persons-companies) 页面**：两种 账户类型的**所有**差异（钱包、卡片、成员、KYC/KYB）汇总在一张 表中，并列出每个限制对应的错误。 * **卡片指南按账户类型重组**："个人账户"与"企业账户"标签页，各自 包含完整流程（首张卡、后续卡，企业还包括公司卡与员工卡的发放） —— 不再需要从零散的注释里拼凑流程。 * **国家示例回到各自指南中**：payout 与 payin 按通道的请求/响应 重新收录在各产品的指南**内部**（每个产品一页，无需跳转到单独的 参考页）。旧 URL 会自动重定向。 * **Postman 实时新鲜度**：Postman 页面现在会显示集合距上次更新的 时长（秒/分钟/天），叠加在日期和版本之上。 * 编译版 MD 现在包含完整的端点参考及文档版本号。 **文档 — 站点全面改版** * **新导航**：快速开始 → 概念 → 集成流程 → 产品 → 集成 → 资源， 每页配有图标与面包屑导航。 * **新页面**：[环境与测试](/zh/environment-testing)（本地开发的 webhook 隧道 + 上线检查清单）、[已启用的服务](/zh/concepts/services)、 [状态与生命周期](/zh/concepts/statuses)（含失败 payout 的 `status_code` 目录）、 [流水与对账](/zh/concepts/movements-reconciliation)，以及带端到端 图示的 [集成流程](/zh/flows)。 * **payout 与 payin 拆分**：通用指南 + 国家参考，包含每个通道的 真实请求与响应。 * **指南扩充**：快速开始以 webhook 收尾闭环；个人资料 （`PATCH /v1/me`）与带角色的成员管理；完整的幂等端点表；webhook 重试计划；链上确认时间；EUR 银行账户；banking 错误加入目录；FAQ 涵盖限额、取消与对账。 * **卡片：何时发送 `cardholder`，已澄清。** 指南与规格现在说明， 账户的**首次发卡**会创建并验证持卡人（完整数据 + 必需文件）， 而**后续**发卡无需数据即可复用 —— 此前的最简示例曾让人误以为 永远不需要数据。 **新增** * **`GET /v1/rates` 中的 `payin_rate`**：每个国家现在携带你的两个 汇率 —— payout（付款）用 `rate`，payin（法币收款/入金）用 `payin_rate`。报价 = 入账，始终如此。 **变更** * **payin 定价现在与 payout 一致**：payin 的汇率定价体现在你的 `payin_rate` 中（入账严格按该汇率换算），payin 费用改为**每笔 固定金额** —— 不再有单独的百分比。每笔 payin 的 `fx_rate` 字段 记录所应用的汇率。参见 [费用](/zh/concepts/fees) 与 [收款指南](/zh/guides/payins)。 * 入账换算向下取整到微 USDT（扣款仍向上取整），差额最多 1 微 USDT。 **文档** * **KYC/KYB：完整的身份字段参考。** `customer` 对象一直接受比示例 更多的可选字段（出生日期、国籍、带签发国的证件、别名、居住地、 公司注册数据……），提供它们能让筛查更精确。 [KYC 指南](/zh/guides/kyc) 现在记录了每个字段，附完整身份示例 与去重规则。 **新增** * **卡片目录**：`GET /v1/cards/catalog/occupations` 与 `GET /v1/cards/catalog/business-activities`（可用 `?q=` 搜索）， 用于填充选择器。指定个人时，`occupation` 必须是目录中的**代码**； 企业则同样要求 `kind_of_business`。目录之外的值会在到达发卡方 之前被 `400 invalid_occupation` / `400 invalid_kind_of_business` 拒绝。参见 [卡片指南](/zh/guides/cards)。 **新增** * **`GET /v1/services`**：你账户已启用服务的生效映射（`payouts`、 `payins`、`transfers`、`crypto`、`banking`、`kyc`、`cards`）—— 可用于决定 UI 中展示的内容。服务按你的商业协议逐账户启用；某项 服务关闭时，其操作返回新的 `403 service_disabled` 错误（读取与 在途资金绝不会被阻断）。 **新增** * **虚拟卡与实体卡**，直接从账户的 USDT 余额消费，无需预充值： 每笔消费都会针对可用余额与卡片限额进行实时授权。个人：1 张虚拟 卡 + 1 张实体卡；企业：不限量，可为公司本身或指定人员（如员工） 发放。新增端点 `POST/GET /v1/cards`、`GET/PATCH /v1/cards/{id}` （限额与冻结/解冻）、`POST /v1/cards/{id}/activate|cancel|reveal` 以及 `GET /v1/cards/{id}/transactions`。参见 [卡片指南](/zh/guides/cards)。 * **新增计费服务**（固定、可配置、可为 0）： `card_creation_virtual`、`card_creation_physical`、`card_monthly` （余额不足时卡片被冻结 —— 不产生欠款）以及 `card_cancellation`。 * **新增 webhook** `card_transaction`（已授权/已撤销/已调整）与 `card_status_changed`（状态变化，包括自动冻结）。 * **新增总账流水类型**：`card_debit`、`card_refund`、`card_fee`、 `card_fee_refund`。 **新增** * **智利：托管支付页（`method: "fintoc"`）**，位于 `POST /v1/payins`。响应携带一个 `payment_url`，付款人打开后即可 从**任意智利银行或钱包**（Banco Estado、Santander、Mach、Tenpo、 Mercado Pago 等）转账；存款会被自动检测、校验并以 USDT 入账， 并发送常规的 `payin_credited` webhook。支持可选的 `idempotency_key`：重试会返回同一笔 payin 和同一个 URL，不会 开启第二个支付会话。参见 [收款指南](/zh/guides/payins)。 **新增** * **所有列表端点均支持 `from`/`to` 日期筛选**：`/v1/movements`、 `/v1/payouts`、`/v1/payins` 与 `/v1/crypto/transactions` 现在在 常规分页（`page`、`page_size` 上限 200）之外接受 `from`/`to` （YYYY-MM-DD，UTC，含端点日期）。无效日期返回 `400 invalid_range`。 * **查询内部转账**：`GET /v1/transfers`（带分页与日期筛选的列表） 与 `GET /v1/transfers/{id}` —— 此前只能创建。 * **列出 webhook 订阅**：`GET /v1/webhooks/subscriptions`。 * **主动收款的幂等性**：`POST /v1/payins/collect` 现在要求 `idempotency_key`（它执行真实扣款；重试绝不会向付款人重复扣款）。 钱包创建（重试不重复收费）与管理员调整也做了同样加固。 * `members`、`crypto/wallets`、`deposit-accounts` 及（管理端） `orgs` 增加了统一分页。 * **账户对账单**（`GET /v1/reports/statement`）：将期间内的所有 流水 —— payout、payin、加密、内部转账与费用 —— 汇总为一份可审计 的文档，并进行精确的会计对账 （`opening + inflows − outflows = closing`，与总账核对）。同一 端点提供三种格式：面向网页的 **JSON**、带 CBPay 品牌的 **PDF**， 以及带数值单元格、筛选器和流水表、面向审计师的多工作表 **Excel** （`format=json|pdf|xlsx`，`lang=es|en`）。组织管理员可以生成其 任意账户的对账单。参见 [指南](/zh/guides/statement)。 **改进** * **文档全站的可视化流程图**：介绍页的资金地图（进出 USDT 余额的 一切）、带扣款/冻结/退款的 payout 生命周期、两步 QR 流程、汇入 入账的四种 payin 模式、加密充值与提现、完整的 banking 生命周期、 KYC 状态、webhook 投递与重试，以及幂等决策规则（"我该用哪个键 重试？"）。 **变更** * **新基础 URL：`https://api.qbank.cl/platform`**（此前为 `exchange.qbank.cl/platform`）。旧域名作为别名继续可用，因此 现有集成不会中断 —— 但新集成请一律使用 `api.qbank.cl`。全部 文档、规格与 Postman 集合均已指向新 URL。 **新增** * **Banking**：为你的账户开立真实银行账户 —— 通过国际银行网络 （视货币而定，SEPA、SWIFT、ACH）接收、持有和汇出资金。 `/v1/banking/*` 下新增 14 个端点： * 银行档案：创建、查询、上传文件并提交验证。 * 账户：按货币开立、列出并查询实时余额。 * 收款人：登记、列出并关联目标账户。 * 付款：报价（`prepare`，免费）并以幂等方式执行 `TRANSFER`/`WITHDRAW`。 * 新增 webhook：`banking_customer_status_changed` 与 `banking_operation_status_changed`。 * 新增费用（固定、可配置、操作失败时退款）：`banking_customer`、 `banking_account`、`banking_operation` —— 每个响应中的 `banking_fee` 字段显示实际收取的金额。 * 完整的 [Banking 指南](/zh/guides/banking)，含端到端流程及每种 操作的示例。 **改进** * **API 参考完全本地化**：以西班牙语浏览文档时，标题、描述、字段 与侧边栏分组现在均已翻译（此前只有界面框架会切换语言）。 * payout 指南重组：巴西 PIX 现在仅出现在"按国家的示例"下（重复的 章节已删除）；QR 因为是不同的流程（扫码 + 确认），仍作为唯一 单独的流程章节保留。 * Webhooks：**5 个事件各自**的示例负载。 * 快速开始：个人**与**企业两种注册示例。 * **Postman 集合扩充到 53 个请求**：具有多种用例的端点现在按用例 各提供一个请求（每个国家和方式一个 payout、按模式的 payin、 个人/企业 KYC 等），每个都带有可直接发送的请求体。 * **收款指南按国家重构**，与 payout 对齐：通道矩阵展示各国模式， 外加智利 / 秘鲁 / 墨西哥 / 委内瑞拉 / 玻利维亚 / 巴西标签页及其 完整示例。 * **新增 [FAQ 页面](/zh/faq)**：沙盒、初始入金、payout 前成本 估算、汇率保证、到账时间、安全重试、无参考码的存款等 —— 上手 第一天的问题都能在文档内找到答案。 * 快速开始以**关键信息**表开篇（基础 URL、认证请求头、slug、金额 格式、环境），并附 `GET /v1/rates` 响应示例与成本估算公式。 * payout：方式与银行目录的响应示例，外加一张标注对余额影响的状态 表。payin：目录响应示例及 `delivery` 的含义。 **改进** * **文档全站按用例提供完整示例**： * payout：每个国家和方式各一个示例，含其真实的 `beneficiary` 与 响应（智利、秘鲁 CCI + Yape、墨西哥 CLABE + 借记卡、委内瑞拉 Pago Móvil + 银行转账、玻利维亚 ACH、巴西 PIX、巴拉圭）。 * payin：玻利维亚与巴西 QR 并排展示，主动收款 `c2p` 与 `debito_inmediato` 及其 OTP 响应，专属存款账户。 * KYC/KYB：个人、企业与最简自动填充请求，附筛查、重新筛查与 监控（启用/停用）的响应。 * 内部转账：按邮箱、按 `account_id`、企业→个人（发薪）与幂等 重放。 * 加密：个人 vs 企业的钱包创建，以及 `wallet_limit_reached` 错误。 * API 参考：每个端点均可选择命名示例（10 个 payout 通道、3 种 payin 模式、个人/企业 KYC……）。 **新增** * **巴西（BRL）PIX** 在 payout 与 payin 中的文档： * 通过 `POST /v1/payouts` 按密钥（CPF/CNPJ、手机、邮箱或 `evp` 随机密钥）进行 `pix` payout。 * 通过 `qr/scan` + `qr/confirm` 流程（`country: "BR"`）向 PIX QR （静态或 "copia e cola"）付款。 * 通过 `POST /v1/payins`（`method: "qr"`，`country: "BR"`）使用 动态 PIX QR 收款，携带二维码图片与 "copia e cola" 代码。 * 通过预告银行转账收款（`method: "bank_transfer"`）。 通道的启用是渐进的；目录（`GET /v1/payouts/methods`、 `GET /v1/payins/methods`）反映任一时刻的可用性。 **新增** * **所有收款（payin）方式现已通过 API 提供**： * `POST /v1/payins` 现在接受 `method`：`qr`（QR 收款，同以往）或 `bank_transfer`（预告一笔入账存款，并获取转账必须携带的参考码 以便自动入账）。 * `POST /v1/payins/collect` —— 在支持的通道（如委内瑞拉 `c2p` / `debito_inmediato`）进行主动拉取收款，同步入账；当方式要求 预先 OTP 时使用 `POST /v1/payins/collect/otp`。 * `POST /v1/payins/deposit-accounts` —— 绑定到你账户的固定专属 存款账户（如墨西哥 CLABE）：汇入该账户的一切都会自动入账。 使用 `GET /v1/payins/deposit-accounts` 列出它们。 * 指南中提供了 payout 的完整通道与方式矩阵（智利、秘鲁含 `yape`、 墨西哥 SPEI、委内瑞拉含 `pago_movil`、玻利维亚含 `qr`、巴拉圭）。 * 委内瑞拉（VES）加入 `GET /v1/rates` 报价。 **新增** * **玻利维亚 QR payout**：分两步支付任意玻利维亚收款二维码 —— `POST /v1/payouts/qr/scan`（免费，返回收款人数据）与 `POST /v1/payouts/qr/confirm`（按常规 payout 收费：你的汇率 + 固定费用，同步返回最终结果，失败时自动退款）。 * 玻利维亚（BOB）加入 `GET /v1/rates` 报价。 **新增** * 新增 **[Postman](/zh/postman)** 页面：官方可下载集合，包含全部 25 个端点、示例请求体与预配置的认证。每个 API 版本都会重新生成。 **变更** * 费用页面与 payout 示例现已反映当前的定价模型：payout 按**你的 汇率 + 每笔固定费用**收取（无单独百分比）。派发等值 100 USDT 会扣除 100 USDT 加上你配置的固定费用。 **改进** * `GET /v1/rates` 现在按国家返回**你账户专属的汇率**：与你的操作 实际执行的汇率相同（`local_amount / rate = USDT`），报价与扣款 之间没有差异。 **移除（Breaking）** * `GET /v1/crypto/deposit-address`（v1.4 中弃用的别名）已被永久 移除。请使用 `POST /v1/crypto/wallets` 创建钱包，并用 `GET /v1/crypto/wallets` 列出它们。 **新增** * **企业多钱包**：企业账户现在可以**每个网络创建不限量的钱包** （个人仍为每个网络 1 个）。 * 新增端点：`POST /v1/crypto/wallets`（创建钱包，可选 `label` 以便区分）与 `GET /v1/crypto/wallets`（列出我的钱包）。每次创建 在配置了固定费用 `wallet_creation` 时计费。 * 当个人尝试在同一网络创建第二个钱包时，新增 `422 wallet_limit_reached` 错误。 * 钱包响应现在包含 `wallet_id` 和 `label`。 **变更** * 加密指南重组为：**创建钱包、查看我的钱包、充值、转账与流水**。 * `GET /v1/crypto/deposit-address` 作为弃用的旧别名保留：请改用 钱包端点。 **修复** * 两种语言的文案与翻译润色；流水表现在包含 `wallet_creation_fee` 与 `wallet_creation_refund` 条目类型。 **改进** * 专业级 API 参考：全部 25 个端点现在为**每种情况**（成功、幂等 重放、以及每个可能的错误及其真实响应体）提供请求与响应示例， 可直接在文档 playground 中试用。 * 5 个 webhook 现已在 API 参考内部文档化（标准 OpenAPI Webhooks 章节），每个事件均含 schema 与示例负载。 * 方式与银行目录以系统的真实响应结构文档化。 * `GET /healthz` 端点已文档化（服务状态）。 * 加密指南新增 **"钱包余额与活动"**：如何查询余额、带 `tx_id` 的 链上活动，以及账务历史。 * 品牌化文案：整套文档现在以 **CBPay** 的口吻表达（此前使用"你的 运营方"或"该组织"之类的泛称）。 * 身份验证在全站文档中统一命名为 **KYC/KYB**（个人为 KYC，企业为 KYB）。 * 内部转账：明确记录其可在**任意组合**的账户之间进行（个人↔个人、 个人↔企业、企业↔企业），且**始终免费**。 **新增** * 新增 `wallet_creation` 费用服务：在每条链上首次创建充值地址可能 收取由 CBPay 配置的固定费用（0 = 免费，默认值）。 `GET /v1/crypto/deposit-address` 响应现在包含 `creation_fee`， 流水历史新增 `wallet_creation_fee` 与 `wallet_creation_refund` 条目类型。获取已存在的地址始终免费；创建失败时费用自动退还。 * 新增 **更新日志** 页面（本页），记录 API 与文档的版本历史。 **变更** * 加密指南现在有一个明确的 **"创建你的钱包"** 章节，说明按网络 创建（首次调用返回 201 并附 `creation_fee`，之后为免费的 200）， API 参考将该端点更名为"创建或获取我的钱包（充值地址）"。 **新增** * 按操作计费的合规费用：`compliance_person`、`compliance_company`、 `compliance_rescreen` 与 `compliance_monitoring`（每次调用的固定 费用；0 = 免费）。KYC 响应现在包含 `compliance_service` 与 `compliance_fee`。 * 新增 `POST /v1/kyc/rescreen` 与 `PATCH /v1/kyc/monitoring` 端点 （停用监控免费）。两者都要求已有 KYC（`409 no_kyc`）。 **变更** * CBPay 官方品牌形象已应用于整套文档。 * 管理相关文档已迁移至 CBPay 内部门户；本站现在仅涵盖账户 API。 **首次发布** * CBPay 公开 API 文档，双语（西班牙语与英语）：认证（JWT 会话与 `pk_` API key）、USDT 资金模型、费用、幂等性、多国法币 payout、 payin、内部转账、加密（链上入金与提现）、KYC、签名 webhook 及 完整的错误目录。 * 基于 OpenAPI 3.1 生成的交互式 API 参考。