PayOut 对账

对账 PayOut 意味着将您创建的 Money Movement（支付意图及其最终状态）与实际在您的 Cobre Balance 中移动资金的交易进行匹配，覆盖哥伦比亚、墨西哥和美国的 PayOut 通道。

本指南说明 Money Movement 与交易之间的关联方式、每种终态下对余额的预期影响，以及如何按需或通过报告批量对账。

Money Movement 与交易

每笔 PayOut 涉及两个相关但不同的标识符：

标识符	前缀	生成时机	代表内容
Money Movement ID	`mm_`	PayOut 创建时	支付意图/请求及其生命周期状态
交易 ID	`trx_`	您的 Cobre Balance 被扣款或入账时	实际影响余额的账务记录

一个 Money Movement 可能生成零个、一个或多个交易，具体取决于其生命周期的展开方式。由 Money Movement 产生的每笔交易都带有 metadata.money_movement_id 字段以关联回该 Money Movement —— 使用此字段按生成它的 PayOut 对交易进行分组。

创建 PayOut 时（创建 Money Movement）请始终提供 external_id。该值会在 Money Movement 中原样返回，是将 Cobre 的 PayOut 与您内部的发票、订单或付款记录匹配的最简单方式。

示例 —— PayOut 及其交易如何逐步展开：

已完成的 PayOut

被拒绝的 PayOut（已冲销）

PayOut 生命周期与余额影响

PayOut 的 status.state 表示其是否已完成，其 status.code / status.description 在未完成时说明原因。完整的原因代码目录请见 Money Movement 状态，完整的生命周期模型请见 Money Movement 指南。

终态	典型交易	净余额影响
`completed`	1 笔扣款	负向（资金已发出）
`canceled`	0（在应用扣款之前已取消 —— 例如审批被拒绝）	无
`failed`	0 —— 失败的 PayOut 从不会产生扣款	无
`rejected`	1 笔扣款 + 1 笔冲销贷记（如果扣款已经应用）	无（如已冲销）

就对账而言，failed 与 rejected 并不能互换。failed 涵盖在应用任何扣款之前就被发现的运营/平台层面问题（例如余额不足、超出限额、处理错误）—— 此时永远不会有交易可查。rejected 涵盖通道或银行层面的拒绝，可能发生在扣款已经入账之后 —— 这正是下方产生冲销贷记的情形。

如果收款银行在 Cobre 已确认完成之后又退回了资金，PayOut 有时会从 completed 转变为 rejected。发生这种情况时，Cobre 会在您的 Cobre Balance 上应用一笔冲销贷记交易。对账时不要将 completed 视为永久最终的余额状态 —— 请始终检查同一个 money_movement_id 下是否存在后续的冲销交易。

特别是在墨西哥的 SPEI PayOut 中，被退回的转账会生成一笔 spei_return 贷记交易，用以抵消原始的 spei_debit —— 通过匹配同一个 money_movement_id 下的这两种交易类型来对账墨西哥 PayOut 的冲销。

按需对账 PayOut

需要核查某个特定 PayOut 或一小批 PayOut 时，直接查询获取所有 Money Movement（GET /money_movements）：

过滤条件	用途
`state`	筛选出 `completed`、`rejected`、`failed` 或 `canceled` 的 PayOut
`external_id`	根据特定的内部引用查找 Money Movement（包含匹配）
`source_id` / `destination_id`	对账某个 Cobre Balance 发出的或某个交易对手方收到的所有 PayOut
`created_at_gte` / `created_at_lte`	将查询限定在某个日期范围内
`amount`、`amount_gte`、`amount_lte`、`currency`	按金额缩小范围

将结果与获取账户交易记录（GET /accounts/{acct_id}/transactions）交叉核对，筛选 credit_debit_type=debit 并匹配 metadata.money_movement_id，以确认每笔 PayOut 影响余额的那一侧。

批量对账 PayOut

对于按日期范围或大批量的对账，请使用报告，而不是逐页翻阅查询结果：

为 Money Movement 一侧创建报告（CSV 使用 money_movement_csv_v1，JSON 使用 money_movement_v1），并为交易一侧创建报告（CSV 使用 transactions_csv_v1，JSON 使用 account_transactions_v1），两者使用相同的日期范围。

将两份报告都按 metadata.money_movement_id 分组。

恰好只有一条扣款记录的 money_movement_id 对应已完成的 PayOut；同时有一条扣款记录和一条冲销贷记记录的 money_movement_id 对应已冲销的拒绝或失败。

实时对账 PayOut

按需查询和报告都属于拉取（pull）模式。若需实时对账，请改为通过通知与订阅订阅 Money Movement 状态事件 —— PayOut 状态变化时（money_movements.status.completed、money_movements.status.rejected、money_movements.status.failed、money_movements.status.canceled），Cobre 会立即推送 Webhook，让您在事件发生的那一刻更新账目，而不必反复轮询。

Webhook 的投递是尽力而为，并非永久保证送达 —— 重试窗口请见通知与订阅。请将 Webhook 视为您的实时信号，将按需查询或报告视为周期性兜底手段，用于捕获 Webhook 可能遗漏的内容。

期初与期末余额对账

除单笔 PayOut 之外，客户通常还需要对账某个 Cobre Balance 的期初余额、期末余额和每日汇总 —— 无论具体是哪笔 PayOut 生成了每笔交易。完整流程（包括请求/响应示例）请见期初与期末余额对账。

PayOut 对账允许的操作

🔍 查询 — Money Movement

🔍 查询 — 交易

🔍 查询 — 每日余额历史

🔑 报告

说明： 按状态、外部 ID、交易对手方、日期范围或金额按需查询 PayOut。

执行该操作后的预期结果： 返回一份分页的 Money Movement 对象列表，包含其当前 status。

📘 了解更多：

🔗 获取所有 Money Movement

🔗 获取一个 Money Movement

如何开始

每笔 PayOut 都始终提供 external_id

这是将 Cobre 的 Money Movement 与您的内部记录匹配的最快方式，并且可以通过 external_id 过滤条件进行查询。

订阅 Money Movement 状态事件，而不是反复轮询

请见通知与订阅，以近乎实时的方式获得通知，而不必反复查询 API。

了解您所使用通道的原因代码

查阅 Money Movement 状态，以便 failed 或 rejected 的 PayOut 的 code 和 description 是可操作的信息，而不是含糊不清的内容。

提前决定使用按需查询还是报告

对单笔 PayOut 或小批量场景使用按需查询，对按日期范围或大批量场景使用报告。

使用此 API 后的预期结果

每笔 PayOut 都能解析为一组匹配的 Money Movement + 交易

已完成的 PayOut 显示一笔扣款；已冲销的拒绝或失败则在同一个 money_movement_id 下显示一笔扣款和一笔冲销贷记。

期初与期末余额可对照每日余额历史进行验证

每日余额历史中的 initial_balance 和 end_balance，与您根据按序排列的交易手工计算出的结果一致。

差异可精确定位到某个 money_movement_id

任何余额差异都会被缩小到某一笔 PayOut，您可以直接通过其 Money Movement 和交易记录进行排查。

PayOut 对账

Money Movement 与交易#

PayOut 生命周期与余额影响#

按需对账 PayOut#

批量对账 PayOut#

实时对账 PayOut#

期初与期末余额对账#

PayOut 对账允许的操作#

如何开始#

使用此 API 后的预期结果#

Money Movement 与交易

PayOut 生命周期与余额影响

按需对账 PayOut

批量对账 PayOut

实时对账 PayOut

期初与期末余额对账

PayOut 对账允许的操作

如何开始

使用此 API 后的预期结果