报表 - Cobo Payments

本页介绍 Payments 报表类型、用于定义报表范围的通用输入，以及生成和管理报表的入口。

生成报表范围

生成报表时，您可以通过以下通用输入定义报表范围：

start_time：报表时间范围的开始时间
end_time：报表时间范围的结束时间
report_export_format：导出文件的格式
report_types：要生成的一个或多个报表类型
token_ids：可选的代币过滤条件，用于缩小报表范围

您可以使用这些输入定义时间范围、导出格式和报表范围。有关具体的请求与响应机制，请参见下方相关 API 操作。

报表类型及适用场景

当前 Payments 文档已确认以下报表类型：

`report_type`	用途	常见使用场景
`Order`	导出支付订单的汇总数据。	用于订单收款对账，以及查看订单层级的收款活动。
`OrderTransaction`	导出与支付订单相关的交易数据。	用于查看订单模式收款对应的交易记录。
`TopUpTransaction`	导出充值模式的交易数据。	用于充值收款对账，以及查看充值交易记录。
`PayinWeeklyStatement`	导出覆盖订单模式和充值模式的周度收款报表。	用于按周查看各类收款渠道的活动。
`PayinDailyStatement`	导出覆盖订单模式和充值模式的日报收款表。	用于按日查看各类收款渠道的活动。
`CryptoPayout`	导出加密货币转账的交易数据。	用于加密货币转账对账，以及查看转账记录。
`OffRamp`	导出法币 Off-Ramp 转出的交易数据。	用于法币出金对账，以及查看 Off-Ramp 记录。
`Refund`	导出退款交易数据。	用于退款对账，以及查看退款记录。
`PayoutWeeklyStatement`	导出覆盖加密货币转账、法币 Off-Ramp 和退款的周度转出报表。	用于按周查看各类转出渠道的活动。
`PayoutDailyStatement`	导出覆盖加密货币转账、法币 Off-Ramp 和退款的日报转出表。	用于按日查看各类转出渠道的活动。
`PayinCommissionFee`	导出收款侧手续费数据。	用于对账收款相关的手续费。
`PayoutCommissionFee`	导出转出侧手续费数据。	用于对账转出相关的手续费。
`BalanceChange`	导出账户余额变动数据。	用于查看余额变化，支持对账和账户分析。
`Summary`	导出汇总数据，覆盖收款、转出和手续费。	用于从聚合视角查看核心支付活动的对账结果。
`BulkSend`	导出 Bulk Send 的交易数据。	用于批量下发执行结果对账，以及查看 Bulk Send 记录。

不同报表类型覆盖的业务范围不同，因此导出的字段也可能随 report_type 而变化。

常见枚举值说明

以下枚举值来自 Payments OpenAPI 定义，用于帮助理解导出字段中的状态类和类型类字段。

`report_status`

值	含义
`Completed`	报表已成功生成，可供下载或查询。
`Failed`	报表生成失败。

`acquiring_type`

值	含义
`Order`	订单模式。付款人按固定金额订单完成支付，适合单次购买或固定金额场景。
`TopUp`	充值模式。付款人向专属充值地址打款，适合灵活充值或按用量结算场景。

`payout_channel`

值	含义
`Crypto`	通过链上加密货币转账完成转出。
`OffRamp`	通过法币出金通道转至已登记的银行账户。

`refund_type`

值	含义
`Merchant`	退款金额从商户余额扣除。
`Psp`	退款金额从开发者余额扣除。

`flow_direction`

值	含义
`in`	资金流入 `source_account`。
`out`	资金流出 `source_account`。

`source_type`

值	含义
`Init`	初始化导致的余额变动。
`OrderIn`	订单模式收款导致的余额变动。
`LatePayment`	迟到付款导致的余额变动。
`TopUp`	充值模式收款导致的余额变动。
`UnexceptedIn`	非预期入账导致的余额变动。
`RefundOut`	退款转出导致的余额变动。
`Payout`	转出导致的余额变动。
`UnexceptedOut`	非预期出账导致的余额变动。
`Allocation`	资金分配导致的余额变动。
`SettlementNetwork`	结算网络（Settlement Network）活动导致的余额变动，例如结算网络交易完成后在您的 Payment 账户中完成资金结算时。
`BulkSend`	Bulk Send 导致的余额变动。

支付订单 `status`

值	含义
`Pending`	订单已创建，但尚未检测到入账交易。
`Processing`	已检测到入账交易，订单正在处理中。
`Completed`	订单已完成，所需支付金额已收齐。
`Expired`	订单已过期，或被更新接口显式取消。
`Underpaid`	订单已过期，且曾收到付款，但金额不足。

转出 `status`

值	含义
`Pending`	转出已创建，等待处理。
`Preparing`	正在准备转出。
`Transferring`	正在向收款目标执行转账。
`Completed`	转出已成功完成。
`PartiallyCompleted`	部分转账成功，部分失败。
`Failed`	转出失败，没有成功完成的转账。
`RejectedByBank`	被收款银行拒绝，仅适用于 OffRamp。

退款 `status`

值	含义
`AddressPending`	用户已打开退款链接，但尚未提交退款地址。
`AddressSubmitted`	退款地址已提交。
`Pending`	退款单已创建，但退款交易尚未发起。
`Processing`	退款处理中，至少有一笔退款交易在执行。
`Completed`	所有退款交易均已成功完成。
`PartiallyCompleted`	部分退款交易成功，部分失败。
`Failed`	所有退款交易都失败。
`PendingConfirmation`	退款单已创建，但尚未指定 `to_address`。补齐地址后会转为 `Pending`。

交易 `status`

值	含义
`Submitted`	交易请求已提交到系统，等待进入后续处理流程。
`PendingScreening`	交易正在等待筛查。
`PendingAuthorization`	交易正在等待授权检查，这里既可能包括人工审批，也可能包括内部风控、KYT 或合规检查。
`PendingSignature`	交易已通过前置检查，正在等待签名或签名相关处理。
`Broadcasting`	交易正在广播到链上网络。
`Confirming`	交易已上链，正在等待足够的区块确认数。
`Completed`	交易已成功完成。
`Failed`	交易处理失败。
`Rejected`	交易被拒绝，没有进入成功执行路径。
`Pending`	交易处于待处理状态，通常表示尚未进入明确的执行阶段。

高频交易 `sub_status`

`sub_status“ 用于解释交易具体卡在哪个细分环节。完整清单较长，下面列出 Payments 报表里最常见、最值得关注的一组：

值	含义
`PendingCoboKYTCheck`	正在等待 Cobo KYT 检查。
`RejectedKYT`	因 KYT 检查未通过而被拒绝。
`PendingRiskControlCheck`	正在等待风控检查。
`PendingApproverCheck`	正在等待审批人审批。
`RejectedByCobo`	因未满足 Cobo 合规要求而被拒绝。
`PendingWaitSigner`	正在等待签名方介入。
`PendingSignerApproval`	正在等待签名人批准。
`PendingSignerProcessing`	签名服务正在处理。
`InsufficientBalance`	可用余额不足。
`InsufficientBalanceFundLocked`	总余额可能足够，但可用余额被锁定，暂时无法发起该交易。
`FailedBroadcasting`	广播到链上网络失败。
`PendingBlockConfirmations`	已广播，正在等待链上确认数达到阈值。
`FailedOnChain`	已上链，但链上执行失败。
`ReplacedByNewTransaction`	原交易已被新交易替换，例如加速或替换 nonce 场景。
`RejectedByCoboKYT`	因 Cobo KYT 检查未通过而被拒绝。

导出字段与字段差异

每种报表类型都会导出一组固定且有序的列。在导出文件中，每个列标题都是根据下方内部列键生成的可读显示标签；例如，时间列的列标题会带有 UTC+8 后缀，如 Created Time(UTC+8)、Updated Time(UTC+8) 和 Expiration Time(UTC+8)。CryptoPayout 和 Summary 报表类型会在单个 XLSX 文件中导出多个工作表，详见下文对应小节。

`Order`

每一行代表一笔支付订单。

列	说明
`created_time`	订单创建时间；导出列标题为 `Created Time(UTC+8)`。
`order_id`	支付订单的唯一 ID。
`payment_type`	订单记录的业务支付类型，例如产生该订单的收款模式。
`order_status`	支付订单当前状态；见上文“支付订单 `status`”。
`order_tag`	商户为订单附加的标签，用于分组或标记。
`merchant_name`	与订单关联的商户显示名称。
`merchant_id`	与订单关联的商户 ID。
`token`	用于支付订单的代币。
`network`	收到付款的区块链网络。
`paid_amount`	订单实际收到的代币金额。
`payable_amount`	付款人应支付的代币金额。
`product_order_amount`	不含开发者手续费的订单基础金额。
`developer_fee`	订单收取的开发者手续费。
`currency_pair`	用于换算的计价到结算币种对。
`exchange_rate`	将计价金额换算为应付代币金额所用的汇率。
`wallet_name`	接收订单资金的钱包名称。
`wallet_type`	接收钱包的类型。
`updated_time`	订单最近更新时间；导出列标题为 `Updated Time(UTC+8)`。
`expiration_time`	订单过期时间；导出列标题为 `Expiration Time(UTC+8)`。

`OrderTransaction`

每一行代表一笔订单模式收款交易。

列	说明
`created_time`	交易创建时间；导出列标题为 `Created Time(UTC+8)`。
`merchant_id`	与相关订单关联的商户。
`order_id`	该交易所属的支付订单。
`order_status`	相关支付订单的状态；见上文“支付订单 `status`”。
`transaction_id`	交易记录的唯一 ID。
`transaction_status`	交易处理状态；见上文“交易 `status`”。
`transaction_amount`	该交易转移的代币金额。
`from_address`	链上发送地址。
`to_address`	链上接收地址。
`txn_hash`	链上交易哈希。
`token`	转移的代币。
`network`	交易所在的区块链网络。
`developer_fee`	归属于该交易的开发者手续费。

`TopUpTransaction`

每一行代表一笔充值模式交易。

列	说明
`created_time`	交易创建时间；导出列标题为 `Created Time(UTC+8)`。
`payment_type`	充值模式交易记录的业务支付类型。
`transaction_status`	交易处理状态；见上文“交易 `status`”。
`payer_id`	Cobo 分配的付款人标识。
`custom_payer_id`	开发者定义的付款人标识。
`received_amount`	充值收到的代币金额。
`from_address`	链上发送地址。
`to_address`	充值接收地址。
`transaction_id`	交易记录的唯一 ID。
`txn_hash`	链上交易哈希。
`merchant_name`	商户显示名称。
`merchant_id`	商户 ID。
`token`	收到的代币。
`network`	交易所在的区块链网络。
`developer_fee`	归属于该交易的开发者手续费。
`wallet_name`	接收钱包的名称。
`wallet_type`	接收钱包的类型。
`updated_time`	交易最近更新时间；导出列标题为 `Updated Time(UTC+8)`。

`PayinWeeklyStatement`

每一行代表一条覆盖订单模式和充值模式的周度收款报表记录。

列	说明
`period`	该行覆盖的报表周期，周报为一周，日报为一天。
`token`	该行金额使用的代币。
`transaction_number`	该周期内的收款交易总数。
`total_payin_amount`	该周期内的收款总金额。
`order_transaction_number`	订单模式收款交易数量。
`total_order_amount`	订单模式收款总金额。
`topup_transaction_number`	充值模式交易数量。
`total_topup_amount`	充值模式总金额。
`unexpected_transaction_number`	非预期入账交易数量。
`total_unexpected_amount`	非预期入账总金额。
`total_payin_commission_fee`	该周期内的收款手续费总额。

`PayinDailyStatement`

每一行代表一条覆盖订单模式和充值模式的日度收款报表记录。

列	说明
`period`	该行覆盖的报表周期，周报为一周，日报为一天。
`token`	该行金额使用的代币。
`transaction_number`	该周期内的收款交易总数。
`total_payin_amount`	该周期内的收款总金额。
`order_transaction_number`	订单模式收款交易数量。
`total_order_amount`	订单模式收款总金额。
`topup_transaction_number`	充值模式交易数量。
`total_topup_amount`	充值模式总金额。
`unexpected_transaction_number`	非预期入账交易数量。
`total_unexpected_amount`	非预期入账总金额。
`total_payin_commission_fee`	该周期内的收款手续费总额。

`CryptoPayout`

每一行代表一笔加密货币转出记录。该报表始终以 XLSX 文件导出。第一个工作表 payout crypto 覆盖标准加密货币转出。当转出经过跨链路由时，导出会包含第二个工作表 payout crypto with bridge，它重复第一个工作表的所有列，并新增下方列出的跨链相关列。工作表 payout crypto：

列	说明
`created_time`	转出创建时间；导出列标题为 `Created Time(UTC+8)`。
`payout_id`	转出的唯一 ID。
`payment_type`	转出记录的业务支付类型。
`initiator`	发起该笔转出的操作方或 API Key。
`payout_status`	转出状态；见上文“转出 `status`”。
`balance_source`	为该笔转出出资的账户，例如商户余额或开发者余额。
`network`	转出使用的区块链网络。
`token`	发送给收款方的代币。
`to_address`	收款方链上地址。
`total_payout_amount`	该笔转出请求的总金额。
`actual_payout_amount`	实际发送给收款方的金额。
`merchant_names`	为该笔转出出资的商户名称。
`merchant_ids`	为该笔转出出资的商户 ID。
`amounts`	该笔转出的商户金额明细。
`updated_time`	转出最近更新时间；导出列标题为 `Updated Time(UTC+8)`。

工作表 payout crypto with bridge 的新增列（在上述所有列之外）：

列	说明
`original_network`	跨链转换前的源网络。
`original_token`	跨链转换前的源代币。
`payout_network`	跨链后交付的目标网络。
`payout_token`	跨链后交付的目标代币。
`bridge_fee`	该笔转出收取的跨链费用。

`OffRamp`

每一行代表一笔法币 Off-Ramp 转出记录。

列	说明
`created_time`	转出创建时间；导出列标题为 `Created Time(UTC+8)`。
`payout_id`	转出的唯一 ID。
`payment_type`	转出记录的业务支付类型。
`initiator`	发起该笔转出的操作方或 API Key。
`payout_status`	转出状态；见上文“转出 `status`”。
`balance_source`	为该笔转出出资的账户。
`bank_name`	收款银行名称。
`bank_account_number`	收款银行账号。
`total_payout_amount`	该笔转出请求的法币总金额。
`actual_payout_amount`	实际发送给收款方的法币金额。
`merchant_names`	为该笔转出出资的商户名称。
`merchant_ids`	为该笔转出出资的商户 ID。
`amounts`	该笔转出的商户金额明细。
`updated_time`	转出最近更新时间；导出列标题为 `Updated Time(UTC+8)`。

`Refund`

每一行代表一笔退款记录。

列	说明
`created_time`	退款创建时间；导出列标题为 `Created Time(UTC+8)`。
`refund_order_id`	退款单的唯一 ID。
`payment_type`	退款记录的业务支付类型。
`initiator`	发起该笔退款的操作方或 API Key。
`transaction_status`	退款交易状态；见上文“交易 `status`”。
`merchant_name`	与退款关联的商户显示名称。
`merchant_id`	与退款关联的商户 ID。
`order_id`	关联的支付订单 ID。
`token`	退款使用的代币。
`network`	发送退款所在的区块链网络。
`refund_amount`	退款金额。
`to_address`	退款收款地址。
`balance_source`	为退款出资的账户。
`wallet_name`	用于退款的钱包名称。
`wallet_type`	用于退款的钱包类型。
`updated_time`	退款最近更新时间；导出列标题为 `Updated Time(UTC+8)`。
`description`	描述退款的备注。

`PayoutWeeklyStatement`

每一行代表一条覆盖加密货币转出、Off-ramp 转出和退款的周度转出报表记录。

列	说明
`period`	该行覆盖的报表周期，周报为一周，日报为一天。
`token`	该行金额使用的代币。
`transaction_number`	该周期内的转出交易总数。
`total_payout_amount`	该周期内的转出总金额。
`withdraw_crypto_transaction_number`	加密货币转出交易数量。
`total_withdraw_crypto_amount`	加密货币转出总金额。
`off_ramp_transaction_number`	Off-ramp 转出交易数量。
`total_off_ramp_amount`	Off-ramp 转出总金额。
`refund_transaction_number`	退款交易数量。
`total_refund_amount`	退款总金额。
`unexpected_transaction_number`	非预期转出交易数量。
`total_unexpected_amount`	非预期转出总金额。
`total_payout_commission_fee`	该周期内的转出手续费总额。

`PayoutDailyStatement`

每一行代表一条覆盖加密货币转出、Off-ramp 转出和退款的日度转出报表记录。

列	说明
`period`	该行覆盖的报表周期，周报为一周，日报为一天。
`token`	该行金额使用的代币。
`transaction_number`	该周期内的转出交易总数。
`total_payout_amount`	该周期内的转出总金额。
`withdraw_crypto_transaction_number`	加密货币转出交易数量。
`total_withdraw_crypto_amount`	加密货币转出总金额。
`off_ramp_transaction_number`	Off-ramp 转出交易数量。
`total_off_ramp_amount`	Off-ramp 转出总金额。
`refund_transaction_number`	退款交易数量。
`total_refund_amount`	退款总金额。
`unexpected_transaction_number`	非预期转出交易数量。
`total_unexpected_amount`	非预期转出总金额。
`total_payout_commission_fee`	该周期内的转出手续费总额。

`PayinCommissionFee`

每一行代表一条与收款相关的手续费记录。

列	说明
`merchant_id`	归属该手续费的商户。
`transaction_type`	该手续费适用的交易类型。
`source`	被计费交易的业务来源。
`billing_date`	手续费计费日期。
`transaction_amount`	底层交易金额。
`fee_rate`	用于计算手续费的费率。
`fee_amount`	Cobo 收取的手续费金额。
`fee_type`	手续费类别。

`PayoutCommissionFee`

每一行代表一条与转出相关的手续费记录。

列	说明
`merchant_id`	归属该手续费的商户。
`transaction_type`	该手续费适用的交易类型。
`source`	被计费交易的业务来源。
`to_address`	底层转出的收款地址。
`billing_date`	手续费计费日期。
`transaction_amount`	底层交易金额。
`fee_rate`	用于计算手续费的费率。
`fee_amount`	Cobo 收取的手续费金额。
`fee_type`	手续费类别。

`BalanceChange`

每一行代表一条 Payments 账户余额变动记录。

列	说明
`balance_type`	受本次变动影响的余额类型。
`merchant_name`	发生余额变动的商户显示名称。
`merchant_id`	发生余额变动的商户 ID。
`token`	发生变动的余额对应代币。
`network`	与该余额关联的区块链网络。
`amount_raw`	余额变动金额。
`balance_change_type`	余额变动的业务原因。
`source`	触发该次余额变动的来源记录。
`amount_change`	本次余额变动的有符号金额。
`updated_balance`	变动后的余额。
`business_date`	余额变动的业务日期。

source_type 为 SettlementNetwork 的余额变动来自结算网络活动。详情请参考结算网络指南。

`Summary`

每份 Summary 报表汇总收款、转出和手续费活动。 Summary 报表始终以 XLSX 文件导出，包含四个工作表：pay-in、pay-out、commission-fee 和 cobo-bill。每个工作表针对所选时间范围汇总相应的业务活动。

`BulkSend`

每一行代表 Bulk Send 批次中的一个条目。

列	说明
`created_time`	条目创建时间；导出列标题为 `Created Time(UTC+8)`。
`bulk_send_id`	该条目所属 Bulk Send 批次的唯一 ID。
`item_id`	批次内单个条目的 ID。
`transaction_id`	为该条目生成的交易 ID。
`payment_type`	该条目记录的业务支付类型。
`bulk_send_execution_mode`	Bulk Send 批次的执行模式。
`bulk_send_item_status`	单个 Bulk Send 条目的状态。
`balance_source`	为该条目出资的账户。
`network`	该条目使用的区块链网络。
`token`	该条目发送的代币。
`to_address`	该条目的收款地址。
`total_payout_amount`	该条目请求的金额。
`actual_payout_amount`	该条目实际发送的金额。
`merchant_names`	为该条目出资的商户名称。
`merchant_ids`	为该条目出资的商户 ID。
`updated_time`	条目最近更新时间；导出列标题为 `Updated Time(UTC+8)`。

确认所需字段后，您可以使用下方 API 操作生成报表或查询已生成的报表。

概览

初始配置

收款

资金管理

索引信息

报表

生成报表范围

报表类型及适用场景

常见枚举值说明

`report_status`

`acquiring_type`

`payout_channel`

`refund_type`

`flow_direction`

`source_type`

支付订单 `status`

转出 `status`

退款 `status`

交易 `status`

高频交易 `sub_status`

导出字段与字段差异

`Order`

`OrderTransaction`

`TopUpTransaction`

`PayinWeeklyStatement`

`PayinDailyStatement`

`CryptoPayout`

`OffRamp`

`Refund`

`PayoutWeeklyStatement`

`PayoutDailyStatement`

`PayinCommissionFee`

`PayoutCommissionFee`

`BalanceChange`

`Summary`

`BulkSend`

相关 API 操作

​生成报表范围

​报表类型及适用场景

​常见枚举值说明

​report_status

​acquiring_type

​payout_channel

​refund_type

​flow_direction

​source_type

​支付订单 status

​转出 status

​退款 status

​交易 status

​高频交易 sub_status

​导出字段与字段差异

​Order

​OrderTransaction

​TopUpTransaction

​PayinWeeklyStatement

​PayinDailyStatement

​CryptoPayout

​OffRamp

​Refund

​PayoutWeeklyStatement

​PayoutDailyStatement

​PayinCommissionFee

​PayoutCommissionFee

​BalanceChange

​Summary

​BulkSend

​相关 API 操作

生成报表范围

报表类型及适用场景

常见枚举值说明

`report_status`

`acquiring_type`

`payout_channel`

`refund_type`

`flow_direction`

`source_type`

支付订单 `status`

转出 `status`

退款 `status`

交易 `status`

高频交易 `sub_status`

导出字段与字段差异

`Order`

`OrderTransaction`

`TopUpTransaction`

`PayinWeeklyStatement`

`PayinDailyStatement`

`CryptoPayout`

`OffRamp`

`Refund`

`PayoutWeeklyStatement`

`PayoutDailyStatement`

`PayinCommissionFee`

`PayoutCommissionFee`

`BalanceChange`

`Summary`

`BulkSend`

相关 API 操作