Skip to main content
GET
获取 payin

授权

Authorization
string
header
必填

会话 JWT(来自注册/登录)或 API key(pk_...)。 也接受 X-API-Key: <token> 作为替代请求头。

路径参数

payinID
string<uuid>
必填

响应

payin。

payin_id
string<uuid>
account_id
string
kind
enum<string>
可用选项:
qr,
collect,
push,
card,
checkout,
pos
country
string
currency
string
method
string
local_amount
string

本地货币金额,以普通十进制文本表示(例如 "5000000")。 绝不使用科学计数法。

settlement_asset
enum<string>

payin 入账的虚拟余额。checkout 和 POS 收款以其链接资产计价(在使用本地支付方式之前没有 currency/local_amount;收款金额为以该资产计价的 asset_amount)。其他已入账的 payins 在账户配置了非 USDT 的 default_payin_asset 时携带该字段——净入账金额会自动兑换为该资产。

可用选项:
USDT,
USDC,
BTC,
GOLD
asset_amount
string

仅 checkout 和 POS 收款 — 以 settlement_asset 计价的收款金额(所有状态均返回,包括待支付和已过期)。

conversion_status
enum<string>

自动兑换状态——checkout/POS 收款在付款资产与 settlement_asset 不同时出现;其他 payins 在账户配置了非 USDT 的 default_payin_asset 时出现。pending_retry 会自动重试。不适用时省略。

可用选项:
pending_retry,
done
status
enum<string>
可用选项:
pending,
credited,
unassigned,
expired,
failed
reference
string
created_at
string<date-time>
updated_at
string<date-time>
settle_at
string<date-time>

仅适用于配置了结算延迟的银行卡收款 —— 该收款的余额何时可用(created_at 加上 payin_card 费用配置的 settlement_hours)。收款本身立即确认:状态为 credited,payin_credited webhook 在付款时发出;等待到 settle_at 的只是 余额入账(以及自动换汇,如已配置)。在批准或分配时延迟已到期的收款会立即结算。 余额在确认时即结算的收款不包含此字段。

settlement_pending
boolean

当一笔 credited 状态的银行卡收款的余额仍在等待 settle_at 结算时存在 (为 true)。在此期间该收款无法退款(422 settlement_pending)——资金尚未 进入您的余额。余额到账后此字段消失。

settled_at
string<date-time>

该已确认收款的余额实际进入您账本的时间 —— 无结算延迟的收款在确认时即为 此时间;延迟结算的银行卡收款则在计划结算执行时(或机构管理员手动提前释放时)。

fx_rate
string

入账时你的 payin 汇率(付款被接收并转换后出现)。

usdt_gross
string
fee
string
usdt_credited
string

入账到余额的金额。以加密货币或 CBPay 转账结算的 checkout/POS 收款即使没有 fx_rate 也会返回该字段(不适用外汇报价)。

refund_status
enum<string>

仅当该收款存在退款或拒付时出现。由累计金额推导 —— 收款的 status 永不重写。

可用选项:
partial,
full
refunded_amount
string

该收款因退款与拒付累计扣除的 USDT。

refunded_local
string

以原始本地货币累计退还的金额。

failure
object

仅当主动收款的 payin 为 failed 时出现:拒绝来源(provider = 付款人的银行,core = 扣款前校验)以及具体的代码和消息。

payer_source
enum<string>

预告转账与未分配存款 — 付款人身份的来源。declared 由你提交,account_identity 默认使用账户持有人已验证的税号,none 没有可用身份(只能通过参考号匹配), bank_event(未分配存款)从到账的转账中读取。

可用选项:
declared,
account_identity,
none,
bank_event
payer
object

已知时附加到该 payin 的付款人身份。

deposit_instructions
object

向付款人预告的收款银行账户的冻结快照(已配置入金说明的通道上的 bank_transfer 预告 payin —— 目前为 CL、PY、US)。文本创建后不再 变化;QR 图片在读取时以您当前的品牌重新生成。

deposit_instructions_swift
object

国际 SWIFT 变体的冻结快照 —— 仅当该通道配置了 SWIFT 变体时存在 (目前为 US/USD)。与 deposit_instructions(境内电汇)并存, 带有自己的 qr_payloadqr_png_base64

match_method
enum<string>

到账转账与该 payin 的匹配方式(审计线索)。charge_link 表示该存款支付了为此 payin 创建的收款(QR、checkout 链接或卡),并按该收款一对一关联 — 最强信号,无需启发式匹配。 manual_assign 表示由组织管理员手工路由。

可用选项:
charge_link,
reference,
payer_document,
payer_account,
payer_name,
amount_single_candidate,
dedicated_clabe,
collect_settlement,
manual_assign
match_reason
string

unassigned 状态下,存款无法自动匹配的原因 — no_matchambiguous_amount (两个或更多预告金额相同)、ambiguous_payerclaim_lost(另一笔事件先占用了 该预告)或 assigned_to:<payin_id>

candidate_count
integer

与某笔 unassigned 存款的金额和币种匹配的待处理预告数量(2 或更多表示该存款存在歧义)。

最后修改于 2026年8月29日