Skip to main content
账户身份获批后才能通过认证账户收款。 个人账户需要已批准的 KYC，企业账户需要 已批准的 KYB，之后才能创建 payin。此规则适用于 POST /v1/payins（QR、card、 checkout、bank_transfer 和 fintoc）、POST /v1/payins/collect/otp、 POST /v1/payins/collect、POST /v1/payins/deposit-accounts，以及已保存卡扣款和 POST /v1/subscriptions。获批前这些请求返回 HTTP 403 verification_required。
该关卡仅适用于认证账户创建。已经创建的公开支付链接仍可支付，已经收到的被动入账 仍可处理，org-admin 的运营分配仍可用，系统创建的入金工具不受阻止。
在收款中，客户以当地货币付款。账户直接以 USD 入账，精度为 2 位小数；若配置其他资产，则净额按 payin_rate（GET /v1/rates）和固定手续费执行入账后的转换。 无论采用哪种模式，每条路径的终点都相同 —— 自动入账 + webhook：

​
1. 查询可用通道

可用的国家、货币和收款模式由 CBPay 定义。请始终查询目录：
delivery 描述付款在 CBPay 一侧的确认方式（银行通知、轮询或两者兼有） —— 它不会改变您的任何集成方式：您始终会收到 payin_credited webhook。 收款通道和模式：
委内瑞拉（VES）：现在可通过 c2p 进行主动收款。付款人先在其银行 应用中生成 claveDinamica，再将其交给您的集成；集成在 collect 请求的 otp 字段中发送该值。C2P 没有之前的 /collect/otp 请求步骤。 debito_inmediato 不是当前可用的通道。向委内瑞拉的对外付款 （pago_movil、bank_transfer）不受影响：参见 payouts。
可用性可能变化；目录（GET /v1/payins/methods）始终是唯一可信来源。 在所有情况下入账方式相同：按已报价的 payin_rate 折算为 USDT，并在 扣除固定入金费用后净额入账。入账时会按 FIFO 消费 payin 批次；若启用的 库存不足，原报价仍然有效，缺口记录为 spot fallback 并发送运维告警。 如果您希望将收款保留在其他余额（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：
转账到达后，系统会根据转账附言中的参考号进行匹配，您的账户即自动入账。 若参考号未随转账传递，付款人证件号可作为后备依据 — 参见 预告转账的匹配规则。

​
主动扣款（pull）

部分通道支持由付款人授权的 pull 扣款。账户必须先完成身份审核并获批， 才能调用该请求。

​
委内瑞拉 C2P

对于 VE/VES/c2p，付款人先在银行应用中生成 claveDinamica。集成将该值 作为 otp 发送；它不是 CBPay 返回的 OTP，也不存在先申请 OTP 的步骤：
该 request 使用现有 collect 合同。payer_document、payer_phone、 payer_bank 和 otp 是 C2P 所需的付款人数据；otp 携带银行生成的 动态密钥。响应 shape 不变；同步成功时包含 paid: true、 provider_reference 和已入账 payin 的标识。

​
基于 OTP 的 pull 方式

平台会在调用 core 前筛查付款人。命中 hold 时返回 202 in_review，不会扣款； 批准后使用相同 request 重试。如果账户尚未获批，collect 会在执行通道前 返回 403 verification_required。timeout 或 5xx 不授权创建新操作： 保留相同的幂等上下文并跟踪操作状态。请始终检查 GET /v1/payins/methods，因为通道可用性会变化。

​
通用收款链接（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，并请付款人使用 你组织常规的银行信息即可。

​
专用账户元数据与付款人身份

入账到专用收款账户的 push 会返回 instrument_id、instrument 区块和银行 上报的 payer 区块——完整结构见 资金账户指南。 可使用 ?instrument_id=<uuid> 筛选历史。

​
3. 接收入账

当付款到达（无论通过哪种模式），您的账户会自动入账，并触发 payin_credited webhook：
fx_rate 是入账时刻您的 payin_rate —— 折算严格按该汇率进行： usdt_gross = 700.00 / 6.91。出现 rate_source 时，它表示报价来源 （lot 或 spot）；没有加载报价的历史 payin 会省略该字段。 入金对象保留完整的明细：

​
状态

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

​
查询与历史记录

from/to 使用 YYYY-MM-DD（组织时区）；日期无效时返回 400 invalid_range。method 与 kind 用于缩小通道和 payin 类型， refund_status 接受 none、partial 或 full，search 会对 payin ID、 参考号或幂等键进行不区分大小写的部分匹配。

​
常见错误

​
常见问题

订阅 payin_credited：它携带所应用的汇率、手续费和精确的 usdt_credited。你也可以轮询 GET /v1/payins/{id}。
使用 GET /v1/rates 返回并在入账时生效的已报价 payin_rate。检查 payin_rate_source：lot 表示启用的 USDT payin 库存支持了报价， spot 表示使用 spot 路径。您约定的点差已包含在汇率中 —— 绝不会单独列示。
可以 —— 用 PUT /v1/settlement 设置 default_payin_asset。账户直接以 USD 分入账；其他已配置目标使用入账后转换流程， 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。只有确实要收两笔款时，才为每笔传入不同的键值。
走廊会同时发布两条轨道，付款人可任选其一：境内轨道 （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 把账户信息渲染成 二维码，仅仅是移动端的复制捷径：付款人扫码后得到一段多行文本 （银行、账户、持有人、金额、备注），再把它粘贴到自己银行的转账表单中—— 转账本身仍由付款人自己确认。不要围绕它构建”扫码即付”的流程；应把它和 纯文本字段放在一起展示，让付款人始终可以手动输入。

​
卡支付入账时间

对于卡支付，settlement_hours 决定付款确认后余额何时可用。该字段只能是 0 或 24 的倍数：0 表示余额立即可用，24 表示一个美国工作日，48 表示两个美国工作日。工作日按组织时区计算，为周一至周五，并排除已调整日期的美国联邦假日。例如，周五 15:00 加 48 小时会在没有假日时于周二 15:00 入账；周六加 48 小时也会在周二入账。27 等值会返回 HTTP 400 invalid_settlement_hours。付款会立即确认并变为 credited，只有余额等待 settle_at。已经计算出的 settle_at 和旧的非 24倍数配置继续按日历小时处理。

​
保留本地法币

使用 PATCH /v1/accounts/{accountID} 设置 fiat_hold_local: true，未来 BOB、MXN、ARS 收款保留为本地余额，历史入账不变。credit_asset 始终返回，fiat_credited 仅用于本地法币，usdt_credited 仍是等值 USDT。银行卡使用 USD 入账，自动转换、checkout swap 和 OTC 报价跳过保留收款。
refunded_amount 使用 credit_asset 的单位（USDT 使用微型 USDT，BOB/MXN/ARS 使用法币最小单位）。usdt_credited 始终使用微型 USDT。请按 credit_asset 分支；当 credit 为法币时，绝不要计算 usdt_credited - refunded_amount。

​
USD 作为主账本资产

账户的 settlement_asset 与 payin_settlement_asset 默认值为 USD，可随时用 PUT /v1/settlement 更改；进行中的操作不会重新报价。 USD 账本金额使用美分（两位小数）。直接入账、扣账、费用以及支持 USD 资产字段的 payout、checkout、POS 和卡片流程使用 USD。USD 与 USDT 之间 的 swap 按 1:1 计价，不使用 FX 预言机。BOB、MXN、ARS 仍是独立的法币 账本资产；同币种 payout 直接从这些余额扣账（见 payouts）。 USD 主账户的 payin 直接入账时，响应包含 credit_asset: USD 以及以美分 表示的 fiat 入账金额；usdt_credited 仍用于 USD 等值报表。争议 hold 跟随实际入账资产：USD 入账使用 hold_asset: USD。disputed 与 held 使用 hold 资产的单位； disputed_usdt 与 held_usdt 是归一化后的等值字段。
最后修改于 2026年10月17日