哥伦比亚 PayIn 对账

在哥伦比亚对账 PayIn，意味着将为某次收款（Direct Link、Checkout 或 R2P）创建的 Money Movement 与其在您的 Cobre Balance 上产生的贷记交易进行匹配 —— 但有两个重要例外：静态 Cobre Key 和 Transfer-In 账户参考，二者都绝不会创建 Money Movement。

本指南涵盖哥伦比亚特有的 PayIn 行为。有关 Money Movement 通用生命周期模型，请见 Money Movement；有关 PayOut 对账，请见 PayOut 对账；有关余额层面的对账，请见期初与期末余额对账。

Money Movement 与交易

标识符	前缀	生成时机	代表内容
Money Movement ID	`mm_`	创建 PayIn（Direct Link、Checkout 或 R2P）时	收款意图及其生命周期状态
交易 ID	`trx_`	PayIn 完成并入账时	实际影响余额的账务记录

创建 PayIn 的 Money Movement 时请始终提供 external_id。该值会原样返回，是将 Cobre 收款与您内部发票或订单匹配的最简单方式。

这不适用于静态 Cobre Key 或 Transfer-In 账户参考 —— 详见下文。二者都没有 Money Movement，也没有 external_id；各自使用自己的引用字段进行对账（Cobre Key 使用 metadata.key_value，Transfer-In 使用 metadata.account_reference）。

示例 —— Direct Link PayIn（PSE）及其交易如何逐步展开：

创建 Money Movement

{
  "id": "mm_z4ICqZzfIdG4A3",
  "external_id": "ORDER-2025-050",
  "type": "direct_link",
  "geo": "col",
  "status": {
    "state": "initiated",
    "code": "",
    "description": ""
  },
  "source_id": "cp_5YFeIDhNkz",
  "destination_id": "acc_SsMCnqmUvS",
  "currency": "cop",
  "amount": 10000,
  "created_at": "2025-10-31T01:14:10Z",
  "updated_at": "2025-10-31T01:14:10Z"
}

付款人完成支付 —— 应用贷记交易

{
  "id": "trx_lTTesMeNSbn1zA5RWeOX",
  "type": "r2p_credit",
  "account_id": "acc_SsMCnqmUvS",
  "amount": 10000,
  "previous_balance": 0,
  "current_balance": 10000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2025-10-31T01:14:50Z",
  "created_at": "2025-10-31T01:14:51Z",
  "metadata": {
    "sender_bank_code": "1019",
    "money_movement_id": "mm_z4ICqZzfIdG4A3",
    "description": "CustomRef123",
    "sender_name": "John Doe",
    "r2p_method": "pse",
    "tracking_key": "1890417980",
    "sender_id": "97710251"
  }
}

该交易的 metadata.money_movement_id（mm_z4ICqZzfIdG4A3）即是将其关联回该 Money Movement 的字段 —— 对账时您需要按此字段进行分组。

Money Movement 达到 completed 状态

{
  "id": "mm_z4ICqZzfIdG4A3",
  "external_id": "ORDER-2025-050",
  "type": "direct_link",
  "geo": "col",
  "status": {
    "state": "completed",
    "code": "",
    "description": ""
  },
  "source_id": "cp_5YFeIDhNkz",
  "destination_id": "acc_SsMCnqmUvS",
  "currency": "cop",
  "amount": 10000,
  "created_at": "2025-10-31T01:14:10Z",
  "updated_at": "2025-10-31T01:14:51Z"
}

请将此与下方的静态 Cobre Key 或 Transfer-In 收款进行对比 —— 二者完全没有 Money Movement，也没有 money_movement_id。

哥伦比亚的贷记交易类型

根据收款方式的不同，哥伦比亚已完成的 PayIn 会产生以下交易类型之一：

交易类型	收款方式	是否由 Money Movement 支撑？
`col_credit`	Connect Account 贷记（由银行上报）	是
`col_cb_credit`	Cobre Balance 贷记（Direct Link / Checkout —— PSE、Bancolombia）	是
`r2p_credit`	Request to Pay（PSE）	是
`dd_credit`	Direct Debit 注册收款	是
`col_top_up_credit`	充值	是
`r2p_breb_credit`	Bre-B Direct Link / Checkout（基于 Bre-B 的 Request to Pay）	是
`breb_credit`	静态 Cobre Key	否 —— 详见下文
`transfer_credit`	Transfer-In 账户参考	否 —— 详见下文

breb_credit 和 r2p_breb_credit 会直接在交易中携带付款人的发送方信息（sender_name、sender_id、sender_account_number）。这是哥伦比亚唯一一类无需额外查询即可获得付款人信息的通道 —— 请见哥伦比亚退款处理。

静态 Cobre Key 不会创建 Money Movement

Cobre Key 是一种静态的 Bre-B key：一旦创建，任何持有它的人都可以随时向其转账，而无需 Cobre 发起或跟踪某个具体的付款请求。由于没有请求可供跟踪，Cobre Key 收款不会创建任何 Money Movement—— 它只会直接在您的 Cobre Balance 上产生一笔 breb_credit 交易，并将 metadata.key_value 设置为收到该笔资金的 Cobre Key。

示例 —— 来自静态 Cobre Key 收款的 breb_credit 交易：

{
  "id": "trx_sVT1Gn3qzHLpll6ThICH",
  "type": "breb_credit",
  "amount": 5000,
  "previous_balance": 0,
  "current_balance": 5000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2025-11-26T01:17:17Z",
  "created_at": "2025-11-26T01:17:17Z",
  "metadata": {
    "sender_account_number": "87041725528",
    "sender_account_type": "dp",
    "sender_bank_code": "1507",
    "sender_id": "97710251",
    "sender_id_type": "cc",
    "sender_name": "JOHN DOE",
    "key_value": "@CB5VLNRMCOBRECOMERCI",
    "description": ""
  }
}

该交易上不存在任何 money_movement_id。metadata.key_value（本例中为 @CB5VLNRMCOBRECOMERCI）才是您的对账键 —— 它标识了您的哪一个 Cobre Key 收到了这笔款项。

Transfer-In 账户参考同样不会创建 Money Movement

Transfer-In 账户参考是 Cobre 为您开通的真实、可重复使用的哥伦比亚银行账号（每个客户最多可开通 300 个）。它没有有效期，可以随时接收 B2B 银行转账 —— 就像静态 Cobre Key 一样，每笔转账背后都没有由 Cobre 发起的请求，因此不会创建任何 Money Movement。每一笔转入的款项都只会直接在您的 Cobre Balance 上产生一笔 transfer_credit 交易，并将 metadata.account_reference 设置为收到该笔资金的 Transfer-In 账户参考。

示例 —— 来自 Transfer-In 收款的 transfer_credit 交易：

{
  "id": "trx_f840c6adace259a504a56bdb6xxxxx",
  "type": "transfer_credit",
  "amount": 54700,
  "previous_balance": 4712500,
  "current_balance": 4767200,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2026-05-19T19:48:07Z",
  "created_at": "2026-05-19T19:48:08Z",
  "metadata": {
    "reference": "0038212345",
    "sender_name": "PEXTO COLOMBIA S",
    "sender_id": "9011830296",
    "sender_bank_code": "1066",
    "tracking_key": "291000003C6051234567",
    "description": "NC TRAN ELEC INTERNA",
    "account_reference": "291000123"
  }
}

该交易上不存在任何 money_movement_id。metadata.account_reference（本例中为 291000123）才是您的对账键 —— 它标识了哪个 Transfer-In 账户参考收到了这笔资金。该交易还直接携带付款人的 sender_name、sender_id 和 sender_bank_code，无需额外查询。

key_value（Cobre Key）与 account_reference（Transfer-In）不可互换——每个产品只会填充自己的字段。请不要编写将其中一个字段作为另一个字段兜底的对账逻辑；应首先根据交易的 type（breb_credit 还是 transfer_credit）进行判断。

PayIn 生命周期与余额影响

哥伦比亚的 PayIn 交易只会在 Money Movement 达到 completed 状态时创建—— 这适用于所有由 Money Movement 支撑的收款方式（Direct Link、Checkout、R2P、Direct Debit）：

终态	是否创建交易？	净余额影响
`completed`	是 —— 1 笔贷记	正向（已收到资金）
`rejected` / `failed`	否	无

静态 Cobre Key 和 Transfer-In 账户参考完全不经历这一生命周期 —— 详见上文。

退款同样会影响对账

哥伦比亚没有专门的退款端点。退还一笔已完成的 PayIn，意味着创建一笔新的 PayOut Money Movement 退还给付款人，该操作会产生独立于原始贷记的扣款交易。对账时，不要假设 completed 的 PayIn 对余额的影响是永久性的 —— 在结束该期间的对账之前，请先核查是否存在后续的相关 PayOut。完整流程请见哥伦比亚退款处理。

对账哥伦比亚的 PayIn

按需查询： 对于由 Money Movement 支撑的 PayIn，按 state、external_id、destination_id（您的 Cobre Balance）或日期范围查询获取所有 Money Movement，然后与获取账户交易记录交叉核对，筛选 credit_debit_type=credit 并匹配 metadata.money_movement_id。对于 Cobre Key 或 Transfer-In，请直接查询交易，并按 metadata.key_value 或 metadata.account_reference 进行筛选/分组 —— 这两种情况都没有 Money Movement 可供查询。

批量处理： 通过报告生成 Money Movement 报告（CSV 使用 money_movement_csv_v1，JSON 使用 money_movement_v1）和交易报告（CSV 使用 transactions_csv_v1，JSON 使用 account_transactions_v1），并将导出的行筛选为 currency = COP。将由 Money Movement 支撑的行按 metadata.money_movement_id 分组 —— 已完成的 PayIn 应恰好对应一条贷记记录。Cobre Key 的记录不会有 money_movement_id；请按 metadata.key_value 分组。Transfer-In 的记录同样没有该字段；请按 metadata.account_reference 分组。

实时对账： 请通过通知与订阅订阅事件，而不是反复轮询。对于由 Money Movement 支撑的 PayIn，状态一旦变化，money_movements.status.completed（以及 .rejected / .failed）就会触发。Cobre Key 和 Transfer-In 都没有 Money Movement 可供发出状态事件 —— 请改用 accounts.balance.credit，并通过事件中的 metadata.key_value 或 metadata.account_reference 将其与对应的 Cobre Key 或 Transfer-In 账户参考关联起来。对于 Transfer-In，还应另外订阅 transfer_acc.status.processing / .enabled / .failed，以追踪账户参考何时准备好提供给付款人 —— 这与它之后收到的转账贷记是分开的两件事。

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

哥伦比亚 PayIn 对账允许的操作

🔍 查询 — Money Movement

🔍 查询 — 交易

🔑 报告

说明： 按状态、外部 ID、目标 Cobre Balance 或日期范围按需查询哥伦比亚的 PayIn。不适用于静态 Cobre Key 或 Transfer-In 收款。

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

📘 了解更多：

🔗 获取所有 Money Movement

🔗 获取一个 Money Movement

如何开始

了解哪些收款方式会创建 Money Movement

Direct Link、Checkout、R2P 和 Direct Debit 会创建；静态 Cobre Key 和 Transfer-In 账户参考不会。请据此规划您的对账键：前者使用 money_movement_id，后两者分别使用 metadata.key_value（Cobre Key）或 metadata.account_reference（Transfer-In）。

在由 Money Movement 支撑的 PayIn 上始终提供 external_id

可通过 external_id 过滤条件进行查询，是将收款与您内部订单或发票匹配的最简单方式。

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

请见通知与订阅，无需反复查询 API 即可知晓 PayIn 何时完成。

将退款作为独立的 PayOut 进行跟踪

由于哥伦比亚没有专门的退款端点，请留意引用了此前已完成 PayIn 的后续 PayOut。

使用此 API 后的预期结果

已完成的 PayIn 与一笔贷记交易一一对应

被拒绝或失败的 PayIn 不会产生任何影响余额的交易。Cobre Key 或 Transfer-In 收款则完全不经历这一生命周期。

Cobre Key 和 Transfer-In 收款按各自的引用字段对账，而非 money_movement_id

每笔 breb_credit 交易都带有 metadata.key_value；每笔 transfer_credit 交易都带有 metadata.account_reference。这两个字段永远不可互换。

已退款的 PayIn 会体现为关联的后续 PayOut

某个期间的对账需要同时考虑原始贷记以及任何后续的退款扣记。

哥伦比亚 PayIn 对账

Money Movement 与交易#

哥伦比亚的贷记交易类型#

静态 Cobre Key 不会创建 Money Movement#

Transfer-In 账户参考同样不会创建 Money Movement#

PayIn 生命周期与余额影响#

退款同样会影响对账#

对账哥伦比亚的 PayIn#

哥伦比亚 PayIn 对账允许的操作#

如何开始#

使用此 API 后的预期结果#

Money Movement 与交易

哥伦比亚的贷记交易类型

静态 Cobre Key 不会创建 Money Movement

Transfer-In 账户参考同样不会创建 Money Movement

PayIn 生命周期与余额影响

退款同样会影响对账

对账哥伦比亚的 PayIn

哥伦比亚 PayIn 对账允许的操作

如何开始

使用此 API 后的预期结果