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>
instrument_id
string<uuid>

收到 payin 的专用收款工具;通用收款和历史 payin 省略此字段。

instrument
object

工具记录存在时返回的专用工具元数据。

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 在清算资产与入账资产不同时携带该字段(账户配置了不同于入账资产的 default_payin_asset;直接以 USD 入账或以本地法币留存的 payins 不兑换)。

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

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

conversion_status
enum<string>

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

可用选项:
pending_retry,
done
status
enum<string>
可用选项:
pending,
credited,
unassigned,
expired,
failed
reference
string
idempotency_key
string

创建请求中您提供的幂等键,原样返回。当 payin 未携带该键创建 (或由平台自身创建)时省略——内部键永远不会暴露。

created_at
string<date-time>
updated_at
string<date-time>
settle_at
string<date-time>

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

settlement_pending
boolean

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

settled_at
string<date-time>

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

fx_rate
string

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

rate_source
enum<string>

加载报价时的 payin 报价来源;没有报价的历史记录省略。

可用选项:
lot,
spot
usdt_gross
string
fee
string
usdt_credited
string

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

credit_asset
enum<string>

实际入账资产(USDT 或保留的本地法币)。

可用选项:
USD,
USDT,
BOB,
MXN,
ARS
fiat_credited
string

本地法币金额,仅在 credit_asset 为法币时出现。

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 由银行报告,也适用于通过 charge_link 绑定的已支付 QR; 如果通道没有报告某个值,则省略对应字段。

可用选项:
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_payload 和 qr_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_match、ambiguous_amount (两个或更多预告金额相同)、ambiguous_payer、claim_lost(另一笔事件先占用了 该预告)、checkout_link_expired(checkout 链接已过期)或 assigned_to:<payin_id>。

candidate_count
integer

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