Skip to main content
入金（payin）是一笔法币收款：您的客户以当地货币付款，您的账户自动获得 USDT 入账，按您的入金汇率（GET /v1/rates 中的 payin_rate）折算， 并在您的账户配置了固定入金费用时予以扣除。 无论采用哪种模式，每条路径的终点都相同 —— 自动入账 + webhook：

​
1. 查询可用通道

可用的国家、货币和收款模式由 CBPay 定义。请始终查询目录：
delivery 描述付款在 CBPay 一侧的确认方式（银行通知、轮询或两者兼有） —— 它不会改变您的任何集成方式：您始终会收到 payin_credited webhook。 收款通道和模式： 可用性可能变化；目录（GET /v1/payins/methods）始终是唯一可信来源。 在所有情况下入账方式相同：按您当前的 payin_rate 折算为 USDT，并在 扣除固定入金费用后净额入账。如果您希望将收款保留在其他余额（USDC、BTC 或 GOLD），请配置 default_payin_asset — 参见 资金模型。

​
2. 选择模式并创建收款

每个国家都有自己的收款模式。各模式的真实请求与响应如下：
托管支付页面（fintoc） —— 推荐：您会获得一个 payment_url； 付款人打开它后可从任意智利银行或钱包（Banco Estado、Santander、 Mach、Tenpo、Mercado Pago……）转账。付款会被自动检测并校验 —— 无需手动填写参考号。
响应 201：
将 payment_url 分享给付款人（链接、重定向或 WebView）。付款确认后， 您的账户即以 USDT 入账，并收到 payin_credited webhook。CLP 金额必须为 整数（智利比索没有小数位），支付会话默认在 24 小时后过期。使用相同的 idempotency_key 重试会返回同一笔入金和同一个 URL —— 绝不会开启第二个 支付会话。预告银行转账（手动的替代方案）：预先申报即将到来的存款，并把 参考号分享给汇款人。
响应 201：
转账到达后，系统会根据转账附言中的参考号进行匹配，您的账户即自动入账。 若参考号未随转账传递，付款人证件号可作为后备依据 — 参见 预告转账的匹配规则。

​
通用收款链接（checkout）

通用收款链接现已拥有独立指南，涵盖报价引擎、所有支付轨道与公开端点：

Checkout 收款链接

一个链接，付款人自行选择支付方式 — 所有已开通国家的法币、加密货币、银行卡或 CBPay 应用 — 结算到你选择的余额。

​
已保存卡片与循环扣款（card）

已保存凭证（COF）与计划性订阅已移至独立指南：

已保存卡片与订阅

在持卡人同意下保存卡片，一键或在持卡人不在场时扣款，并安排循环订阅。

​
退款（card）

已入账的银行卡收款可以全额或部分退款，资金从你的余额扣除，并生成对应的 分录、凭证与 Webhook：

退款

全额或部分退回银行卡收款、撤销当日授权，并了解拒付如何自动入账。

​
预告转账的匹配规则

预告转账（method: "bank_transfer"）没有支付会话：付款人从自己的银行转出， 因此存款在到账时才被识别。匹配按以下顺序执行，命中即停止：
  1. reference —— 转账附言中的 12 位代码。
  2. 付款人证件号 —— 预告中的 payer_document 与银行报送的付款人比对 （点、连字符与校验位均忽略）。
  3. 唯一候选 —— 该金额与货币下恰好只有一笔待处理预告。
若三者都无法唯一对应到一笔预告 —— 同一金额有两笔待处理预告、没有参考号、 也没有付款人证件号 —— 系统不会靠猜入账：该存款以 unassigned 落地，由你的 CBPay 运营人员路由。钱不会丢失，它已经在收款账户中。

​
标识付款人（可选，推荐）

method: "bank_transfer" 接受付款人数据。所有字段均为可选且向后兼容 —— 现有集成无需改动即可继续工作：
响应中始终包含 payer_source，便于你的结账页决定该向付款人索取什么：
少于 5 个字符或不含数字的证件号会被丢弃为弱信号（无法与金额或银行代码区分）。 预告仍会创建，且 payer_source 会如实反映覆盖情况。

​
重试与幂等

预告接受 idempotency_key（请求体）或 Idempotency-Key 请求头。使用相同 键值重试会返回原始预告 —— 相同的 reference —— 并带上 idempotency_hit: true 与 HTTP 200，而不会创建第二笔预告。
两笔完全相同的存活预告（同一账户、货币、金额与付款人）正是匹配拒绝解析的场景： 真实存款与两者都匹配，最终以 unassigned 落地。因此未带键值的 POST 会复用 已存在的相同存活预告，而不是再创建一笔（同样返回 200 与 idempotency_hit: true）。若要向同一付款人收取两笔真实付款且金额相同，请为每一笔传入不同的 idempotency_key —— 每个键值都会创建各自的预告与 reference。
幂等键在账户内按逻辑操作唯一：若你复用一个已用于其他收款方式 （QR、checkout、卡支付）的 idempotency_key，API 会返回 409 idempotency_conflict，而不是返回与请求不符的对象。

​
入金说明：应该转到哪里

在你的组织已为转账通知类收款登记了收款账户的走廊（目前是智利、巴拉圭与美国）， 通报的响应中会包含一个 deposit_instructions 区块——付款人需要转账的确切 银行账户，金额和 reference 已经内置在一段可直接复制的二维码文本中：
响应 201（含入金说明）
你也可以在创建 payin 之前预览收款账户——便于在付款人确认之前，先告诉 他们应该把钱转到哪里：
响应 200
在 US/USD 走廊中，预览会返回两个区块：deposit_instructions 下的境内轨道，以及（当您的组织配置了国际变体时） deposit_instructions_swift 下的 SWIFT 轨道（结构相同，带有自己的 QR）。轨道字段在不使用它们的走廊上直接缺省（而非空值）：
响应 200（美国）
预览端点的 qr_payload 没有 Amount/Reference 这两行（此时还没有实际 的 payin）；而实际通报中内置的那段文本始终包含这两行，这样付款人无需手动 输入任何内容即可完成支付。通报中的这两个区块是一份冻结的快照：如果你的 CBPay 运营方之后更新了登记的账户，已经存在的通报仍会指向创建时使用的账户 ——只有新的通报才会采用变更后的账户。
如果该走廊尚未登记任何收款账户，此端点会返回 404 not_found——处理方式 与下方的 422 deposit_instructions_unavailable 相同：此时还不能向付款人 展示任何账户。
GET /v1/payins/{id} 与列表接口（GET /v1/payins）会原样返回同样的 deposit_instructions（以及存在时的 deposit_instructions_swift）区块， 因此你的前端无需从创建响应中缓存它。在未登记 收款账户的走廊上，该字段直接缺省——此时展示 reference，并请付款人使用 你组织常规的银行信息即可。

​
3. 接收入账

当付款到达（无论通过哪种模式），您的账户会自动入账，并触发 payin_credited webhook：
fx_rate 是入账时刻您的 payin_rate —— 折算严格按该汇率进行： usdt_gross = 700.00 / 6.91。 入金对象保留完整的明细：

​
状态

无法唯一对应到某一笔预告的存款会保持 unassigned 状态，直到 CBPay 团队将其 路由到某个账户（参见预告转账的匹配规则）。分配后， 按目标账户的汇率和费用入账，并同时关闭其所属的那笔预告。
当一笔待支付的代收（二维码或 checkout）在未收到付款的情况下终止时，payin 会自动从 pending 变为 expired（或 failed），并且您会收到 payin_expired webhook。不产生任何资金变动：如需重新 收款，请创建新的 payin。

​
查询与历史记录

from/to 使用 YYYY-MM-DD（组织时区）；日期无效时返回 400 invalid_range。

​
常见错误

​
常见问题

订阅 payin_credited：它携带所应用的汇率、手续费和精确的 usdt_credited。你也可以轮询 GET /v1/payins/{id}。
入账时刻生效的 payin_rate（见 GET /v1/rates）。你约定的点差已包含在 汇率中 —— 绝不会单独列示。
可以 —— 用 PUT /v1/settlement 设置 default_payin_asset。入账仍先进入 USDT，随后立即按真实价格转换；conversion_status 报告 done 或 pending_retry（自动重试）。
你会收到 payin_expired，该 payin 关闭且不发生任何资金变动。创建一个新 的收款即可 —— 没有任何扣款或入账。
参考号仍会匹配到该笔预告，但入账金额以实际到账金额为准。若一笔转账无法对应 到任何预告，则保持 unassigned 状态等待对账；你的 CBPay 团队可以手动将其 分配到正确的 payin。
不会靠猜。如果付款人证件号也无法区分二者，两笔预告都保持 pending，存款以 unassigned 落地交由运营人员路由。在预告中传 payer_document，正是把这种 情形变成自动入账的关键。
不必 —— 它是可选的，不传也不会有任何中断。省略时会使用该账户已验证的税号 （payer_source: account_identity），覆盖持有人自存的场景。当由第三方为你的 客户付款时再传它，并始终向付款人展示 reference。
不会。带上 idempotency_key（请求体或 Idempotency-Key 请求头）时，重试会 返回原始预告并带 idempotency_hit: true。即使未带键值，与某笔存活预告完全相同 的 POST（同一账户、货币、金额与付款人）也会复用它 —— 复制会因歧义而让真实存款 落到 unassigned。只有确实要收两笔款时，才为每笔传入不同的键值。
响应和 GET /v1/payins/{id} 会持久化 failure 块，包含通道的代码和消息 （例如证件与付款人银行登记不符）。修正输入后用新的 key 重试。
走廊会同时发布两条轨道，付款人可任选其一：境内轨道 （deposit_instructions）使用 routing_number（ABA），适用于在美国境内 开户的汇款方（wire 或 ACH）；国际轨道（deposit_instructions_swift）使用 swift（BIC）以及经由代理行的 intermediary_bank_name / intermediary_bank_swift，适用于从美国境外汇款的发送方。两条轨道都汇入 您组织的同一收款安排，并共享同一个 reference（CB…）——付款人将其填入 所选转账的 memo / 附言栏位，这就是自动入账的匹配依据。电汇通常在同一 个工作日内到账并被上报；ACH 视汇款银行可能需要一到三个工作日 —— 只要银行 上报入金，入账与 payin_credited webhook 立即发生。
银行之间并没有针对任意收款账户的统一二维码标准（不同于结账时商户的收款 二维码）——每家银行对转账信息的编码方式都不同，而且大多数银行 App 根本 无法从第三方二维码自动填充转账信息。qr_png_base64 把账户信息渲染成 二维码，仅仅是移动端的复制捷径：付款人扫码后得到一段多行文本 （银行、账户、持有人、金额、备注），再把它粘贴到自己银行的转账表单中—— 转账本身仍由付款人自己确认。不要围绕它构建”扫码即付”的流程；应把它和 纯文本字段放在一起展示，让付款人始终可以手动输入。
最后修改于 2026年8月10日