修复
- AML 筛查的个人字段格式（指南）：筛查引擎要求
date_of_birth为{year, month, day}对象（纯字符串"YYYY-MM-DD"返回422）、nationality为 ISO-3166 代码的数组、personal_identification[]为{ "issuing_country", "number" }且不带type字段。指南与 spec 示例已按实测验证的格式更新。
新增
- QR Crypto 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金额失败）—— 见测试环境。详见 payouts 指南。
变更
- 通用收款链接 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。详见 收款指南。
新增
- 主动收款失败的拒绝详情：当主动收款（
collect，C2P 或即时扣款） 变为failed时，payin 现在包含failure对象，说明拒绝来源 （provider= 付款人的银行，core= 扣款前校验）以及具体的代码和 消息——在POST的同步响应、GET /v1/payins/{id}和 webhook 中均可 见。此前仅暴露通用的failed状态。详见 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。 详见收款指南。
变更
- 卡支付捕获前认证过滤器：只有当 3-D Secure 验证以认证成功或已尝试
结束、且认证数据完整时，卡扣款才会发送给处理方；未经真实认证的尝试会在
资金移动前被拒绝，付款人可以重试。支付页面还延长了设备数据收集时间
（约 11 秒）以提高发卡行的批准率。在测试环境中，金额以
.44结尾可 模拟被该过滤器拒绝的尝试（完整表格见 测试环境）。
新增
- payin 银行卡支付（
card）：POST /v1/payins接受method: "card"（玻利维亚，BOB 或 USD）并返回payment_url— 一个带有你组织品牌的托管支付页面，付款人在安全字段中输入银行卡并完成其 银行的 3-D Secure 验证。可选字段customer、success_url、failure_url与expires_at。支付确认通过payin_receivedwebhook 送达并像任何 payin 一样入账；若无人支付，payin_expired会关闭该收款。 详见payin 指南。
新增
- swaps 与地址筛查响应中的
account_id：POST/GET /v1/swaps与POST/GET /v1/screenings/addresses的响应现在包含account_id（操作所属的账户）。对单账户集成仅作参考；管理视图用它来归属每条记录。
变更
- 两步登录同样遵循手机号绑定冷却期：登录 2FA 为 SMS/WhatsApp 且
号码为最近绑定且未验证时，登录验证码会通过更强的因素发出（身份
验证器应用，其次登录邮箱），而不是发送到该手机号——登录响应中会
返回实际使用的
channel。没有替代因素时，登录返回403 phone_binding_cooldown，直到冷却期结束。验证码绝不会发送到 从当前会话绑定的号码。详见安全与 2FA 指南。
变更
- 手机号处于冷却期时，OTP 质询自动改用更强的因素：手机号为最近
绑定（24 小时冷却期）时，
POST /v1/otp/challenges在您已注册身份 验证器应用或已验证邮箱的情况下不再阻止 — 质询会自动通过该渠道发出 （层级 totp > email），响应中会返回实际使用的渠道。403 phone_binding_cooldown仅在没有任何替代因素时返回。此前， 即使拥有更强的因素，冷却期也会阻止所有 2FA 放宽操作（甚至包括停用 email 渠道）。详见安全与 2FA 指南。
新增
- AML 筛查 PDF 报告：
GET /v1/aml/screenings/{screeningID}/report可将历史记录中的任一筛查 下载为带你品牌的高管级 PDF 报告 —— 封面呈现决策及其风险信号灯、风险 指标（制裁、观察名单、PEP、负面媒体等）、合并匹配、别名、术语表，以及 列明所查国际数据源的最终背书章节。通过lang=en|es|zh支持三语 （默认英文）。纯读取，无费用。详见 AML 指南 的新章节。 - 新错误码
invalid_language（HTTP 400）：PDF 报告的lang不是en、es或zh。详见错误页面。
- AML 筛查的企业字段：示例与 spec 曾将
tax_id/registration_number/country_of_incorporation记为customer.company的扁平字段，但筛查引擎会以422拒绝。标识符应放在registration_authority_identification，国家放在place_of_registration，incorporation_date为{year, month, day}对象。指南与 spec 已修正（已在生产环境验证）。
新增
- 测试账户生而带有数据:测试环境的每个新账户都自带约 6 个月的 真实感演示历史,覆盖所有产品(payouts、payins、转账、加密、兑换、 卡片、banking、联系人……),余额、对账单和分析报表开箱即用。适用于 所有创建路径(注册、社交登录、管理员创建及控制台的 test/live 开关)。
- 环境完全独立:测试数据不再从生产快照刷新 —— 两个环境之间不复制 任何内容。已更新环境与测试指南。
新增
- 官方 MCP 服务器上线
https://mcp.cbpayapp.com:将你的 AI 编辑器或 助手(Cursor、VS Code、Claude、ChatGPT 及任何 MCP 客户端)连接到本文档 —— 搜索、带真实示例的端点与错误目录,无需离开编辑器。只读、无需身份 验证。新增 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等过滤器同样 生效）。
- 不带
format时响应仍是常规的分页 JSON —— 无兼容性变更。
Breaking — 隔离钱包迁移至
/v1/segregated-wallets- 所有隔离钱包路由从
/v1/wallets*重命名为/v1/segregated-wallets*。 方法、参数、响应结构、费用和 webhook 均不变——只有路径前缀改变。 没有兼容别名：旧的/v1/wallets*路由现在返回404。 - 映射（15 条路由遵循同一模式）：
- 钱包发送/入金的响应、webhook 和回执邮件中的
receipt_url现在指向 新路径。 - 原因：通用前缀
/v1/wallets经常与 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_expiredwebhook 事件，携带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 天）。详情与 安全规则见身份认证 → 会话续期。 - 严格轮换与防盗检测：交换时会吊销该设备之前的 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收款人、OTP000000等）可强制触发其他所有结果。完整指南见 环境与测试。 - 按环境区分的 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。详见 加密货币指南与错误页。
新增 — 余额历史中的银行序列
GET /v1/balances/history的assets现在包含银行账户 （BANK_USD、BANK_EUR）的每日序列，各以自身货币（2 位小数）呈现， 可作为 USDT/USDC/BTC/GOLD 旁的又一筛选项直接绘图。它们仍不计入total_usd聚合——该聚合仅覆盖运营余额。 分析指南已更新。
变更 — 按账户类型的钱包限额
- 充值钱包：每个账户——个人和企业——每个受支持组合（
tron/usdt、eth/usdt、eth/usdc）都恰好持有一个充值钱包，注册时自动免费 开通。POST /v1/crypto/wallets现在仅用于补齐缺失的组合；组合已存在时 对所有账户类型都返回422 wallet_limit_reached（此前企业可创建更多）。 - 隔离钱包：现在个人账户也可使用，每个网络+资产组合限 1 个
（第二次尝试返回
422 wallet_limit_reached）。企业账户仍不限数量。403 company_required错误不再适用于隔离钱包。 - 加密货币与隔离钱包 指南、个人与企业页面及 错误页面已更新。
新增 — 持续交易监控（合规控制）
- 平台现已通过银行级合规控制实时监控每一笔操作。对绝大多数客户而言这是 无感的：不改变任何流程，也不会增加可感知的延迟。
- 新增错误码已记录在错误页面：
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。 - 新增指南：钱包筛查。
新增 — 通过 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，与原有的 base64qr_image并存。直接放进<img>标签即可。
新增 — 合规目录
- 新增
GET /v1/aml/catalogs：构建合规与验证表单所需的全部目录 （性别、各国法律实体形式、收入/财富来源、行业标准、ISO-3166 国家 与行政区划）。这些数据此前无法通过 API 获取。
GET /v1/rates与GET /v1/rates/history的asset_prices区块 不再包含内部字段source；请使用settlement_grade和updated_at来判断价格是否可执行以及其新鲜程度。
新增 — 每个账户自创建起即拥有其充值钱包
- 账户创建时（个人或企业），系统会自动且免费开通其三个加密充值
钱包：
tron/usdt、eth/usdt和eth/usdc。注册完成后，GET /v1/crypto/wallets即可返回这三个地址（开通在后台进行；在 注册的当秒查询可能需要稍等片刻）。 POST /v1/crypto/wallets现在用于创建额外的钱包（企业账户）； 个人账户自注册起已占用每种组合的名额。此变更之前创建的账户已补齐 缺失的钱包。
- 公开账户注册现在按 IP 限流（
429 too_many_attempts）。
新增 — 完整可追溯性：对账单中的银行业务、费用明细拆分与钱包托管
- 更丰富的对账单：新增
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_changedwebhook 现在包含receipt_url。 - 独立钱包托管：每个钱包新增
custody字段（cbpay|client）； 平台会同步完整的链上活动，并发送wallet_external_movementwebhook （在平台之外签名的转账，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"。
新增 — 面向仪表盘的历史序列
GET /v1/rates/history：你账户汇率的演变（每个数据点均含 payout 和 payin 两侧），支持day或hour粒度，并为每种货币 提供带符号的change_pct—— 可直接用于带 “+3.4% / −3.0%” 徽章的 汇率图表。还包含 BTC 和 GOLD 的美元参考序列。GET /v1/balances/history：你余额的每日演变 —— 每种资产一条 序列，包含每日收盘余额（无缺口）、按每日历史价格估值的美元汇总 序列、期间的流入/流出以及当前快照 —— 带图表的余额卡片所需的一切。- 汇率历史以约 90 天的每日汇率回填起步，此后持续记录。
新增 — 带真实性验证的 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 对账单 现在使用品牌的真实 Logo 与 Inter 字体渲染（此前为文字字标），Excel 也在汇总表中加入了 Logo。
新增 — 独立钱包（仅限企业账户）
- 拥有独立余额（不在总账内）的链上钱包：创建
（
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。 - 对账单 与 仪表盘 均包含独立钱包区块。
新增 — 账户资料、凭证与安全
- 密码：自助修改（
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 内的唯一身份：其数据 与文件可在其他产品中复用，无需重复填写或重复上传。指南： 可复用身份。
- 卡片：你账户的首次发卡会从你已通过的验证中自动填充持卡人
身份与文件 —— 你只需发送
occupation和salary_usd。显式提供的 字段仍然优先。 - 合规报告（KYB）：
GET /v1/kyb/submissions/{id}/report下载 该验证的签名合规报告（PDF）。
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。新增指南： 你的账户汇总。- 第三方银行用户（仅限企业）：
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。
新增 — 联系人与按手机号发送
- 联系人簿（
/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（使用其 已保存的地址）。新增指南：联系人。
新增 — 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 验证。
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_updatedwebhook 及新的aml服务开关（kyc开关 现在管控身份验证）。指南：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 报价；总额按当时的有效结算价格换算为所选资产。详情见 资金模型。
- 新增
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 —— 现有的
pendingpayin 不受影响。金额+货币的兜底匹配保持不变。 GET /v1/payins与详情接口在 payin 处于pending期间通过reference暴露预告参考码。
新增 — 巴拉圭收款（预告银行转账）
- 新收款通道
PY/PYG/bank_transfer：通过POST /v1/payins预告存款，你的付款人转账（SIPAP 或收款银行的行内转账）并在备注中 填写reference，款项按你的payin_rate自动以 USDT 入账，与 其他国家一致。指南见 收款。 - 瓜拉尼不使用小数：请预告精确的整数金额（例如
"596000"）。 金额+货币的兜底匹配照常适用。 - 该通道出现在
GET /v1/payins/methods中，且delivery: polling。
新增 — 多币种虚拟余额（USDT、USDC、BTC、GOLD）
- 每个账户现在持有四个独立的虚拟余额：
USDT（运营货币）、USDC、BTC（8 位小数，聪）和GOLD（足金克数，6 位小数， 托管方背书）。它们永不混合，也绝不自动兑换。详情见 资金模型。 GET /v1/balances始终返回全部四个余额（未使用该货币时为 零），GET /v1/movements可用?asset=按货币筛选。- 多币种内部转账：
POST /v1/transfers接受asset（默认USDT，可选USDC、BTC、GOLD）—— 始终在同一货币的余额 之间进行，无兑换、无费用。 - 链上 USDC：创建
eth/usdc钱包，通过以太坊充值与提现 USDC。每笔充值入账到其对应资产的余额。指南见 加密货币。 - 参考价格：
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 会话。完整指南见 社交登录。 - 新增端点：
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。 - 多方式：一个账户可同时拥有密码和多个提供方；仅当提供方返回 已验证邮箱时才会按邮箱自动关联。
- 目录 中的新错误码：
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。
- 新增端点：
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 免除 —— 你的服务器间集成无需 任何改动。 - 目录 中的新错误码：
otp_required、otp_invalid、phone_required、phone_binding_cooldown、too_many_attempts等。
文档 — 个人 vs 企业与统一指南
- 新增 个人与企业 页面：两种 账户类型的所有差异（钱包、卡片、成员、KYC/KYB）汇总在一张 表中，并列出每个限制对应的错误。
- 卡片指南按账户类型重组：“个人账户”与”企业账户”标签页，各自 包含完整流程（首张卡、后续卡，企业还包括公司卡与员工卡的发放） —— 不再需要从零散的注释里拼凑流程。
- 国家示例回到各自指南中：payout 与 payin 按通道的请求/响应 重新收录在各产品的指南内部（每个产品一页，无需跳转到单独的 参考页）。旧 URL 会自动重定向。
- Postman 实时新鲜度：Postman 页面现在会显示集合距上次更新的 时长（秒/分钟/天），叠加在日期和版本之上。
- 编译版 MD 现在包含完整的端点参考及文档版本号。
文档 — 站点全面改版
- 新导航：快速开始 → 概念 → 集成流程 → 产品 → 集成 → 资源， 每页配有图标与面包屑导航。
- 新页面：环境与测试（本地开发的
webhook 隧道 + 上线检查清单）、已启用的服务、
状态与生命周期（含失败 payout 的
status_code目录）、 流水与对账，以及带端到端 图示的 集成流程。 - 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字段 记录所应用的汇率。参见 费用 与 收款指南。 - 入账换算向下取整到微 USDT（扣款仍向上取整），差额最多 1 微 USDT。
- KYC/KYB：完整的身份字段参考。
customer对象一直接受比示例 更多的可选字段（出生日期、国籍、带签发国的证件、别名、居住地、 公司注册数据……），提供它们能让筛查更精确。 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拒绝。参见 卡片指南。
新增
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。参见 卡片指南。 - 新增计费服务（固定、可配置、可为 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_creditedwebhook。支持可选的idempotency_key：重试会返回同一笔 payin 和同一个 URL，不会 开启第二个支付会话。参见 收款指南。
新增
-
所有列表端点均支持
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）。组织管理员可以生成其 任意账户的对账单。参见 指南。
改进
- 文档全站的可视化流程图：介绍页的资金地图（进出 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 指南，含端到端流程及每种 操作的示例。
改进
- API 参考完全本地化：以西班牙语浏览文档时，标题、描述、字段 与侧边栏分组现在均已翻译（此前只有界面框架会切换语言）。
- payout 指南重组：巴西 PIX 现在仅出现在”按国家的示例”下（重复的 章节已删除）；QR 因为是不同的流程（扫码 + 确认），仍作为唯一 单独的流程章节保留。
- Webhooks：5 个事件各自的示例负载。
- 快速开始：个人与企业两种注册示例。
- Postman 集合扩充到 53 个请求：具有多种用例的端点现在按用例 各提供一个请求（每个国家和方式一个 payout、按模式的 payin、 个人/企业 KYC 等），每个都带有可直接发送的请求体。
- 收款指南按国家重构，与 payout 对齐：通道矩阵展示各国模式， 外加智利 / 秘鲁 / 墨西哥 / 委内瑞拉 / 玻利维亚 / 巴西标签页及其 完整示例。
- 新增 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……）。
- payout：每个国家和方式各一个示例，含其真实的
新增
- 巴西（BRL）PIX 在 payout 与 payin 中的文档：
- 通过
POST /v1/payouts按密钥（CPF/CNPJ、手机、邮箱或evp随机密钥）进行pixpayout。 - 通过
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 页面：官方可下载集合，包含全部 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 参考。