账户 Linkage 对账

**主账户（primary account）**是资金汇总归集的 Cobre Balance、账户或交易对手方。**次账户（secondary account）**是一个配置为将其收到的每笔贷记自动转发给主账户的 Cobre Balance。本指南介绍如何对账 linkage 产生的 Money Movement 与交易链条，将其关联回原始收款，并处理自动归集未发生的情况。

关于如何启用和配置该关联本身，请见 Account Linkeage。本指南假定 linkage 已配置完成，重点介绍如何对其产生的结果进行对账。

自动归集链条

对于次账户上收到的每一笔贷记，Cobre 都会生成一条固定的链条：一个 Money Movement，以及两个账户上的交易 —— 几乎实时，按每笔交易处理，没有批处理窗口：

贷记到达次账户

{
  "id": "trx_bC9k2QwXz7Ap",
  "type": "breb_credit",
  "account_id": "acc_SecondaryM01",
  "amount": 500000,
  "previous_balance": 0,
  "current_balance": 500000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2026-08-19T14:02:10Z",
  "created_at": "2026-08-19T14:02:11Z",
  "metadata": {
    "key_value": "@MERCHANTONE",
    "sender_name": "JOHN DOE"
  }
}

Webhook：accounts.balance.credit（次账户）。

Cobre 创建自动 Money Movement

{
  "id": "mm_sWp84LtRq2Nx",
  "external_id": "trx_bC9k2QwXz7Ap",
  "geo": "col",
  "status": {
    "state": "completed",
    "code": "",
    "description": ""
  },
  "source_id": "acc_SecondaryM01",
  "destination_id": "acc_PrimaryCOP01",
  "currency": "cop",
  "amount": 500000,
  "created_at": "2026-08-19T14:02:12Z",
  "updated_at": "2026-08-19T14:02:14Z"
}

Webhook：money_movements.status.completed。其 external_id 携带原始贷记交易的 ID —— 正是这一环节将自动生成的 Money Movement 关联回触发它的那笔收款。

次账户被扣款

{
  "id": "trx_sD3fGh81pQr",
  "type": "col_cb_debit",
  "account_id": "acc_SecondaryM01",
  "amount": -500000,
  "previous_balance": 500000,
  "current_balance": 0,
  "currency": "cop",
  "credit_debit_type": "debit",
  "transaction_date": "2026-08-19T14:02:13Z",
  "created_at": "2026-08-19T14:02:14Z",
  "metadata": {
    "money_movement_id": "mm_sWp84LtRq2Nx"
  }
}

Webhook：accounts.balance.debit（次账户）。

主账户被入账

{
  "id": "trx_pC7mNw92Ldz",
  "type": "col_cb_credit",
  "account_id": "acc_PrimaryCOP01",
  "amount": 500000,
  "previous_balance": 1200000,
  "current_balance": 1700000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2026-08-19T14:02:14Z",
  "created_at": "2026-08-19T14:02:15Z",
  "metadata": {
    "money_movement_id": "mm_sWp84LtRq2Nx"
  }
}

Webhook：accounts.balance.credit（主账户）。这一环节确认资金已完成汇总。

如果您订阅了 accounts.balance.credit，将会收到所有余额（主账户和次账户）的贷记事件。请通过 content.account_id 而不是事件键来区分它们。

关联整条链路以进行对账

对象	关联字段	值
原始贷记交易	—	其自身的 `id`
自动生成的 Money Movement	`external_id`	原始贷记交易的 `id`
次账户扣款交易	`metadata.money_movement_id`	自动生成的 Money Movement 的 `id`
主账户贷记交易	`metadata.money_movement_id`	自动生成的 Money Movement 的 `id`

对于流入次账户的 Direct Link / R2P 收款，同一个 money_movement_id 已经追踪了原始贷记以及两个自动环节 —— 不需要再单独解析 external_id 这一环。

从主账户发起的 PayOut 的对账方式与本平台上任何其他 PayOut 相同：通过 metadata.money_movement_id。请见 PayOut 对账。

按地区划分的交易类型

哥伦比亚：

类型	含义
`col_cb_debit`	某个哥伦比亚 Cobre Balance 被扣款，以向另一个 Cobre Balance 转移资金
`col_cb_credit`	某个哥伦比亚 Cobre Balance 从另一个 Cobre Balance 收到一笔贷记
`col_debit`	转出至哥伦比亚金融机构的交易（例如从主账户发起的本地 PayOut）
`col_credit`	来自哥伦比亚金融机构的转入交易（例如被拒绝的 PayOut 退回至主账户）

应用到 linkage 流程中：次账户 → 主账户的扣款为 col_cb_debit，对应的主账户贷记为 col_cb_credit。

墨西哥： 对应的环节在次账户上使用 spei_credit，随后是自动生成的 Money Movement、次账户上的 spei_debit，以及主账户上的 spei_credit。

完整列表请见交易类型目录。

最小可行的 Webhook 订阅

对账一笔 linkage 收款并不需要订阅全部四个事件：

次账户贷记（将 accounts.balance.credit 筛选为次账户的 account_id）告诉您某个商户收到了一笔付款 —— 在此处登记该笔收款。

主账户贷记（将 accounts.balance.credit 筛选为主账户的 account_id）告诉您资金已完成汇总。

自动生成的 Money Movement 和次账户扣款事件有助于在出现异常时追溯整条链路，但登记收款本身并不需要它们。请将主账户贷记视为内部资金汇总，而不是新的收入 —— 收入事件是次账户贷记。

有关如何订阅以及如何按 account_id 区分事件，请见通知与订阅。

归集未自动发生时

情况	行为
在某个次账户配置 linkage 之前，该账户就收到了一笔贷记	不会被追溯性地归集 —— 必须手动转移。
自动生成的 Money Movement 失败	资金将保留在次账户上；不会自动重试。
从主账户发起的 PayOut 先完成，随后又转为延迟拒绝	不会自动冲销。请从主账户发起一笔新的 Money Movement 作为退款 —— 它不会关联回原始交易。
从主账户发起的 PayOut 被拒绝	资金以一笔贷记交易的形式返回主账户，并伴随一个 `money_movements.status.rejected` 事件。
创建 Cobre Balance	不存在对应的 Webhook —— 请通过创建时的响应或轮询该账户来确认。
区分 FX 环节与本地转账	与 FX 相关的 Money Movement 会在其 `metadata` 中携带 `fx_quote` 信息；本地转账则没有。

手动转移资金

当对账发现存在未归集的余额时，请在您自己的账户之间发起一笔常规的 Money Movement 来转移资金：

POST /money_movements
{
  "source_id": "acc_SecondaryM01",
  "destination_id": "acc_PrimaryCOP01",
  "amount": 500000,
  "external_id": "manual-sweep-acc_SecondaryM01-2026-08-19",
  "metadata": {
    "description": "Secondary to Primary manual sweep"
  },
  "checker_approval": false
}

也可以通过 Portal 完成此操作：Movimientos → Unitario → Mover Dinero → Enviar，选择次账户作为来源，选择主账户（在 Cuentas Propias 下）作为目标。

账户 Linkage 对账允许的操作

🔍 查询 — Money Movement

🔍 查询 — 交易

说明： 查询某次 linkage 归集所对应的自动 Money Movement，或在对账发现未归集余额时创建一笔手动 Money Movement。

执行该操作后的预期结果： 返回一个带有 external_id（自动归集）或您自己的引用（手动归集）以及 status 的 Money Movement 对象。

📘 了解更多：

🔗 获取所有 Money Movement

🔗 获取一个 Money Movement

🔗 创建 Money Movement

如何开始

确认您要对账的账户已配置 linkage

请见 Account Linkeage。在配置 linkage 之前收到的贷记永远不会被追溯性地归集。

至少订阅 accounts.balance.credit，并按 account_id 分流处理

请见通知与订阅。如果您需要追溯完整链路而不只是登记收款，请再加上自动 Money Movement 和次账户扣款事件。

了解每个环节适用的关联字段

自动生成的 Money Movement 上是 external_id，两笔结果交易上均为 metadata.money_movement_id —— 在依赖它们之前，请确认您所在地区这两个字段确实已被填充。

为异常情况构建手动归集路径

linkage 配置之前的贷记，以及失败的自动 Money Movement，都需要通过 API 或 Portal 手动转移资金。

使用此 API 后的预期结果

每笔 linkage 收款都能解析为一条完全关联的链路

原始贷记、自动生成的 Money Movement，以及两笔结果交易，都通过 external_id 和 metadata.money_movement_id 相互关联。

对账只会登记该笔收款一次

次账户贷记是收入事件；主账户贷记是内部资金汇总，不是第二笔收款。

异常会表现为未归集的次账户余额

任何未能自动归集的部分都会表现为次账户上的一笔余额，您可以通过一笔手动 Money Movement 来解决。

账户 Linkage 对账

自动归集链条#

关联整条链路以进行对账#

按地区划分的交易类型#

最小可行的 Webhook 订阅#

归集未自动发生时#

手动转移资金#

账户 Linkage 对账允许的操作#

如何开始#

使用此 API 后的预期结果#

自动归集链条

关联整条链路以进行对账

按地区划分的交易类型

最小可行的 Webhook 订阅

归集未自动发生时

手动转移资金

账户 Linkage 对账允许的操作

如何开始

使用此 API 后的预期结果