创建 payin(充值收款)
需要已批准的账户身份；个人账户必须通过 KYC，企业账户必须通过 KYB，之后才能通过此认证操作创建或扣款 payin。 创建一笔法币充值。使用 method: "qr"(默认)会通过处理方生成主动 QR 收款——在玻利维亚为本地互通 QR,在巴西为动态 PIX QR,其 charge 携带 QR 图片和 “copia e cola” 载荷。使用 method: "bank_transfer" 会预告存款,响应携带付款人必须附上的参考号,以便到账转账被自动匹配入账——一个 12 位字母数字短码,适配任何银行附言字段(部分通道上限 20 个字符且不允许特殊字符)。使用 method: "fintoc"(智利)响应携带托管 payment_url:付款人打开后可从任意智利银行或钱包转账;存款会被自动检测、校验并入账。使用 method: "card" 响应携带一个托管 3-D Secure 银行卡收银台的 payment_url,页面带有您组织的品牌 —— 支持玻利维亚(BOB)与以美元结算的国际银行卡(country: "US";任意国家发行的 Visa、Mastercard、American Express、Discover 与 Diners);银行卡数据绝不经过您的集成。使用 method: "checkout" 响应携带一个公开的 checkout_url —— 以您选择的虚拟余额计价的通用收款链接(settlement_asset:USD、USDT、USDC、 BTC、GOLD、SILVER 或 PLATINUM;法币 BOB/MXN/ARS 会被拒绝)。付款人可选择任何有可用 payin 走廊的国家(本地金额实时报价)、四个加密货币选项之一(带可扫描二维码的专属充值地址),或通过商户的 CBPay 二维码/别名从 CBPay 应用即时付款;每笔付款自动兑换为结算资产(以相同资产付款则不兑换)。最先完成支付的方式生效。创建收款免费;存款入账时收取 payin 费用。未发送 stored_card_id 时，开放的 pending/challenge 银行卡会话可按同一账户、国家、币种、金额和 payer_reference 复用 （缺少时回退到 customer.email），返回 HTTP 200、session_reused: true 和原有的 payment_url。会话默认 60 分钟，显式过期时间最多 48 小时。 每个账户最多 50 个开放会话；无法驱逐零尝试的 pending 会话时返回 429 too_many_open_card_sessions。
授权
会话 JWT(来自注册/登录)或 API key(pk_...)。
也接受 X-API-Key: <token> 作为替代请求头。
请求头
JSON idempotency_key 的替代方式。当 body 未提供该键时， method: "card" 必须使用此 header；QR 收款可选。body 与 header 不要发送不同的值。
256^[^\r\n]{1,256}$请求体
走廊国家。除 checkout 外所有方式必填;对 checkout 为可选,仅用于在页面上预选付款人的国家。
"BO"
走廊货币。除 checkout 外所有方式必填;checkout 会以 400 拒绝该字段 —— 收款以 settlement_asset 计价。
"BOB"
正数十进制字符串。走廊方式为本地货币金额;checkout 以 settlement_asset 计价("50" USDT、"0.001" BTC、"2" 克黄金)。
传递给核心的可选渠道提示。
收款过期时间(秒)。对 checkout 取值 600 到 604800(10 分钟到 7 天;默认 24 小时)。
收款模式。qr 通过处理方创建主动 QR 收款;bank_transfer 预告一笔入账存款并返回需附在转账附言中的参考号;fintoc(仅智利)返回托管 payment_url,付款人可从任意智利银行或钱包转账,存款自动检测;pix(仅巴西)返回 PIX 跳转收银台的托管 payment_url (payer_name 与 payer_document 必填,最低 1 BRL);card 返回托管 3-D Secure 银行卡收银台的 payment_url (玻利维亚用 BOB,或当 country 为 US 时收取以美元结算的国际银行卡);checkout 返回一个公开的 checkout_url,付款人在页面上自行选择支付方式(QR、银行卡、银行转账或加密货币)。pull 收款请使用 /v1/payins/collect。
qr, bank_transfer, fintoc, card, checkout, wallet, pix 对于 method: "card"，该键为必填：在 body 中发送，或使用 Idempotency-Key 请求头。qr、bank_transfer、fintoc、pix 与 checkout 可选。使用相同键重试会返回原始 payin、HTTP 200 和 idempotency_hit: true —— 托管方式返回同一个 payment_url/checkout_url，预告银行转账返回同一个 reference —— 而不会开启第二笔收款。对预告转账而言，这直接决定 资金能否入账：两笔金额相同且没有付款人身份的存活预告无法区分， 到账存款会停留在 unassigned。若省略该键，我们仍会把完全相同的 重试（同一账户、货币、金额与付款人证件号）合并到原始预告；当您确实 需要针对同一金额与同一付款人创建两笔独立收款时，请发送不同的键。
256^[^\r\n]{1,256}$银行卡收银台的可选账单预填(card 方式)。付款人可在页面上补充或更正。
Show child attributes
Show child attributes
可选的公共 https URL(card 与 checkout 方式),支付获批后将付款人重定向至此。
可选的公共 https URL(card 与 checkout 方式),支付失败或过期时将付款人重定向至此。
银行卡支付会话的可选 RFC3339 过期时间(card 方式)； 至少提前 5 分钟，创建后最多 48 小时；默认 60 分钟。
仅 checkout —— 收款计价与结算的虚拟余额。每笔付款入账时自动兑换为该资产(以相同资产付款则不兑换)。须为您的组织启用(否则返回 422 settlement_asset_disabled)。省略时使用账户的 payin 结算资产(payin_settlement_asset,回退为 USD)。BOB、MXN、ARS 会被拒绝 (422 invalid_pair):checkout 不以法币结算。
USD, USDT, USDC, BTC, GOLD, SILVER, PLATINUM 仅 card 方式 — 在托管页面向付款人提供"保存此卡"复选框。仅当付款人勾选（明确同意）且 3-D Secure 支付获批后才存储凭证；随后 payin_received/payin_credited 流程会携带 stored_credential 块，该卡出现在 GET /v1/stored-cards 中。
仅 card 方式 — 付款人的纯文本自定义标识（最多 120 个字符）。 这是复用开放 pending/challenge 会话的首选身份；缺少时使用 customer.email。该值用于限定调用账户内的已保存卡片 discovery 与扣款； 另一个账户中的相同邮箱或引用无法发现或使用该凭证。
120仅 card 方式 — 使用之前保存的卡支付（见 GET /v1/stored-cards）。托管页面跳过卡片 录入并显示已保存的卡；3-D Secure 照常运行。与 save_card 互斥。未知、已撤销或属于其他账户的卡返回 404。 随凭证保存的账单信息会在托管页面自动应用（脱敏摘要 + 编辑链接 — 付款人无需重新输入）。
付款人身份。pix（巴西托管跳转）必填；在预告转账中为可选：当付款人不是账户持有人时， 发起转账的个人或公司名称。
140付款人身份。pix（巴西托管跳转）必填；在预告转账中为可选的付款人税号或身份证件号 （至少 5 个字符，其中至少一位为数字）。省略时使用账户持有人已验证的税号， 因此即使付款人忘记填写参考号，本人存款也能被识别。第三方付款时请填写。
40Hosted 或 collect 付款人电话；部分 wallet 方法要求此字段。
40仅预告转账 — 付款人的银行账号（至少 5 个字符）。可选；当通道上报付款账户时， 这是额外的匹配信号。
40