创建 payin(充值收款)

走廊国家。除 checkout 外所有方式必填;对 checkout 为可选,仅用于在页面上预选付款人的国家。

走廊货币。除 checkout 外所有方式必填;checkout 会以 400 拒绝该字段 —— 收款以 settlement_asset 计价。

正数十进制字符串。走廊方式为本地货币金额;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 (玻利维亚用 BOB,或当 country 为 US 时收取以美元结算的国际银行卡);checkout 返回一个公开的 checkout_url,付款人在页面上自行选择支付方式(QR、银行卡、银行转账或加密货币)。pull 收款请使用 /v1/payins/collect。

可选幂等键(bank_transfer、fintoc、card 与 checkout 方式;也接受 Idempotency-Key 请求头)。使用相同键重试会返回原始 payin,HTTP 200 且带 idempotency_hit: true —— 托管方式返回同一个 payment_url/checkout_url,预告银行转账返回同一个 reference —— 而不会开启第二笔收款。对预告转账而言,这直接决定资金能否入账:两笔金额相同、且没有付款人身份的存活预告无法区分,到账存款会停留在 unassigned。若省略该键,我们仍会把完全相同的重试(同一账户、货币、金额与付款人证件号)合并到原始预告;当您确实需要针对同一金额与同一付款人创建两笔独立收款时,请发送不同的键。

可选的公共 https URL(card 与 checkout 方式),支付获批后将付款人重定向至此。

可选的公共 https URL(card 与 checkout 方式),支付失败或过期时将付款人重定向至此。

银行卡支付会话的可选 RFC3339 过期时间(card 方式,至少提前 15 分钟;默认 24 小时)。

仅 checkout —— 收款计价与结算的虚拟余额。每笔付款入账时自动兑换为该资产(以相同资产付款则不兑换)。须为您的组织启用(否则返回 422 settlement_asset_disabled)。

仅 card 方式 — 在托管页面向付款人提供"保存此卡"复选框。仅当付款人勾选（明确同意）且 3-D Secure 支付获批后才存储凭证；随后 payin_received/payin_credited 流程会携带 stored_credential 块，该卡出现在 GET /v1/stored-cards 中。

仅 card 方式 — 你自己的付款人标识（例如你的客户 ID）。已保存的卡片以此引用为范围， 便于列出并扣款正确客户的卡片。纯文本，最多 120 个字符。

仅 card 方式 — 使用之前保存的卡支付（见 GET /v1/stored-cards）。托管页面跳过卡片 录入并显示已保存的卡；3-D Secure 照常运行。与 save_card 互斥。未知或已撤销的卡返回 404。随凭证保存的账单信息会在托管页面自动应用（脱敏摘要 + 编辑链接 — 付款人无需重新输入）。

仅预告转账 — 当付款人不是账户持有人时，发起转账的个人或公司名称。可选。

仅预告转账 — 付款人的税号或身份证件号（至少 5 个字符，其中至少一位为数字）。 可选：省略时使用账户持有人已验证的税号，因此即使付款人忘记填写参考号， 本人存款也能被识别。第三方付款时请填写。

仅预告转账 — 付款人的银行账号（至少 5 个字符）。可选；当通道上报付款账户时， 这是额外的匹配信号。