创建 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,页面带有您组织的品牌 —— 银行卡数据绝不经过您的集成。使用 method: "checkout" 响应携带一个公开的 checkout_url —— 以您选择的虚拟余额计价的通用收款链接(settlement_asset:USDT、USDC、BTC 或 GOLD)。付款人可选择任何有可用 payin 走廊的国家(本地金额实时报价)、四个加密货币选项之一(带可扫描二维码的专属充值地址),或通过商户的 CBPay 二维码/别名从 CBPay 应用即时付款;每笔付款自动兑换为结算资产(以相同资产付款则不兑换)。最先完成支付的方式生效。创建收款免费;存款入账时收取 payin 费用。
授权
会话 JWT(来自注册/登录)或 API key(pk_...)。
也接受 X-API-Key: <token> 作为替代请求头。
请求体
走廊国家。除 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,付款人可从任意智利银行或钱包转账,存款自动检测;card(玻利维亚)返回托管 3-D Secure 银行卡收银台的 payment_url;checkout 返回一个公开的 checkout_url,付款人在页面上自行选择支付方式(QR、银行卡、银行转账或加密货币)。pull 收款请使用 /v1/payins/collect。
qr, bank_transfer, fintoc, card, checkout 可选幂等键(fintoc、card 与 checkout 方式;也接受 Idempotency-Key 请求头)。使用相同键重试会返回原始 payin 及其 payment_url/checkout_url,而不会开启第二个支付会话。
银行卡收银台的可选账单预填(card 方式)—— email、first_name、last_name、address、city、country(纯文本,每个字段最多 120 个字符)。付款人可在页面上补充或更正。
可选的公共 https URL(card 与 checkout 方式),支付获批后将付款人重定向至此。
可选的公共 https URL(card 与 checkout 方式),支付失败或过期时将付款人重定向至此。
银行卡支付会话的可选 RFC3339 过期时间(card 方式,至少提前 15 分钟;默认 24 小时)。
仅 checkout —— 收款计价与结算的虚拟余额。每笔付款入账时自动兑换为该资产(以相同资产付款则不兑换)。须为您的组织启用(否则返回 422 settlement_asset_disabled)。
USDT, USDC, BTC, GOLD