墨西哥 PayIn 对账

在墨西哥对账 PayIn，意味着将某笔 SPEI 收款在您的 Cobre Balance 上产生的贷记交易与其结算的对象或请求进行匹配 —— 使用 metadata.account_reference，这是每笔 spei_credit 交易上的必填字段。该笔收款是否先经过了 Money Movement（Direct Link R2P SPEI）还是没有（与 Cobre Balance 或虚拟 CLABE关联的常设 CLABE），会影响这个 account_reference 值的来源，但不会改变它始终是您对账所依赖的那个键这一事实。

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

Money Movement 与交易

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

创建 Direct Link PayIn 的 Money Movement 时请始终提供 external_id。该值会原样返回，是将 Cobre 收款与您内部发票或订单匹配的最简单方式 —— 但这是 Money Movement 上的字段，不是结果交易上的字段。下文将说明交易本身是如何被标识的。

这不适用于与 CLABE 关联的 SPEI 贷记 —— 详见下文。这类交易没有 Money Movement，也没有 external_id。

示例 —— Direct Link R2P SPEI PayIn 及其交易如何逐步展开：

创建 Money Movement

Cobre 会为此次具体请求生成一个短期有效的动态 CLABE（metadata.virtual_account，默认有效期 5 分钟），并将其提供给付款人。

{
  "id": "mm_8pf9xbiJkAdiAO",
  "external_id": "ORDER-MX-2026-010",
  "type": "direct_link",
  "geo": "mex",
  "status": {
    "state": "initiated",
    "code": "",
    "description": ""
  },
  "source_id": "cp_5YFeIDhNkz",
  "destination_id": "acc_XI7W2HQYuE",
  "currency": "mxn",
  "amount": 10000,
  "metadata": {
    "r2p_rail": "spei",
    "virtual_account": "706180301111111111"
  },
  "created_at": "2025-11-06T16:44:10Z",
  "updated_at": "2025-11-06T16:44:10Z"
}

付款人向该动态 CLABE 发起 SPEI 转账 —— 应用贷记交易

{
  "id": "trx_j51T77qTrVj0lH8TAQlq",
  "type": "spei_credit",
  "account_id": "acc_XI7W2HQYuE",
  "amount": 10000,
  "previous_balance": 0,
  "current_balance": 10000,
  "currency": "mxn",
  "credit_debit_type": "credit",
  "transaction_date": "2025-11-06T16:44:24Z",
  "created_at": "2025-11-06T16:44:24Z",
  "metadata": {
    "account_reference": "706180301111111111",
    "sender_account_number": "002180700856249796",
    "sender_name": "JOHN,DOE/SMITH",
    "reference": "91025",
    "tracking_key": "085905789870328253",
    "description": "Transferencia interbancaria"
  }
}

spei_credit 交易完全没有 money_movement_id 字段。该交易的 metadata.account_reference（706180301111111111）与 Money Movement 的 metadata.virtual_account 相匹配 —— 这正是您用来关联二者的字段。

Money Movement 达到 completed 状态

{
  "id": "mm_8pf9xbiJkAdiAO",
  "external_id": "ORDER-MX-2026-010",
  "type": "direct_link",
  "geo": "mex",
  "status": {
    "state": "completed",
    "code": "",
    "description": ""
  },
  "source_id": "cp_5YFeIDhNkz",
  "destination_id": "acc_XI7W2HQYuE",
  "currency": "mxn",
  "amount": 10000,
  "metadata": {
    "r2p_rail": "spei",
    "virtual_account": "706180301111111111"
  },
  "created_at": "2025-11-06T16:44:10Z",
  "updated_at": "2025-11-06T16:44:24Z"
}

与 CLABE 关联（未涉及 Direct Link）的 SPEI 贷记交易结构完全相同，同样以 account_reference 作为标识 —— 但其背后没有任何 Money Movement，且该 CLABE 是常设的，而不是按请求临时生成的。两者的区分方式详见下文。

墨西哥的贷记交易类型

交易类型	收款方式	是否由 Money Movement 支撑？
`spei_credit`	转入与 Cobre Balance 或虚拟 CLABE 关联的 CLABE 的 SPEI 转账	否 —— 详见下文
`spei_credit`	Direct Link R2P SPEI 收款	是
`mex_credit`	Connect Account 贷记（由银行上报）	是
`internal_spei_credit` / `internal_credit`	Cobre 托管账户之间的内部转账	是

SPEI 贷记交易会直接在 metadata 中携带发送方的账户和身份信息，这也是墨西哥退款能够通过单一端点完成的原因 —— 详见下文。

metadata.account_reference 是每笔 spei_credit 交易上的必填字段，无论是否涉及 Money Movement。它始终是该交易类型的对账键。

与 CLABE 关联的 SPEI 贷记不会创建 Money Movement

与 Cobre Balance 关联的 CLABE，或虚拟 CLABE，可以随时接收 SPEI 转账 —— 就像哥伦比亚的静态 Cobre Key 一样，此时没有由 Cobre 发起并需要跟踪的请求。因此，不会创建任何 Money Movement：该笔转账只会直接在您的 Cobre Balance 上产生一笔 spei_credit 交易。

示例 —— 来自与 CLABE 关联的 SPEI 收款的 spei_credit 交易：

{
  "id": "trx_h5G3wRz88mAxVe2",
  "type": "spei_credit",
  "account_id": "acc_6euTJ0ikgi",
  "amount": 100,
  "previous_balance": 0,
  "current_balance": 100,
  "currency": "mxn",
  "credit_debit_type": "credit",
  "transaction_date": "2025-10-09T19:26:13Z",
  "created_at": "2025-10-09T19:26:14Z",
  "metadata": {
    "account_reference": "706180301111111100",
    "intended_beneficiary_id": "ND",
    "reference": "91025",
    "intended_beneficiary_name": "PEXTO MEXICO",
    "sender_account_number": "002180700856249796",
    "description": "Transferencia interbancaria",
    "sender_name": "JOHN,DOE/SMITH",
    "tracking_key": "085905789870328253",
    "sender_id": "GAAP920820PP7"
  }
}

该交易上不存在任何 money_movement_id。metadata.account_reference（本例中为 706180301111111100 —— 收到资金的常设 CLABE）才是您的对账键。account_id、reference 和 tracking_key 是有用的辅助字段，但应以 account_reference 为匹配逻辑的依据。

相比之下，Direct Link R2P SPEI 收款确实会先创建一个 Money Movement —— 这是一种请求付款（request-to-pay）流程，而不是一个常设的待收账户。其产生的 spei_credit 交易同样通过 metadata.account_reference 进行对账，只不过该值是 Money Movement 自身动态生成的 virtual_account（专为此次请求临时生成的短期 CLABE），而不是常设 CLABE。将交易的 metadata.account_reference 与 Money Movement 的 metadata.virtual_account 进行匹配即可将两者关联起来。

PayIn 生命周期与余额影响

对于由 Money Movement 支撑的收款（Direct Link R2P SPEI），交易只会在 Money Movement 达到 completed 状态时创建：

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

与 CLABE 关联的 SPEI 贷记完全不经历这一生命周期 —— 详见上文。

退款同样会影响对账

墨西哥通过专用端点退还 SPEI 贷记：退还 Money Movement（POST /money_movements_return）。由于 SPEI 贷记交易保留了发送方的账户信息，Cobre 会自动创建目标交易对手方以及一个新的 spei_return Money Movement，并在您的 Cobre Balance 上产生一笔 spei_debit 交易 —— 与原始的 spei_credit 不同，这两笔交易都带有 metadata.money_movement_id。对某个期间进行对账时，不要假设 completed 的 PayIn 对余额的影响是永久性的 —— 在结束该期间的对账之前，请先核查是否存在关联到同一原始交易的后续 spei_debit。完整流程请见墨西哥退款处理。

目前退款仅限于受支持账户提供商上的 spei_credit 交易（首先支持 pr_mex_cobre3，其他即将支持）—— 当前列表请见端点参考文档。

对账墨西哥的 PayIn

按需查询： 对于 Direct Link R2P SPEI，按 state、external_id、destination_id（您的 Cobre Balance）或日期范围查询获取所有 Money Movement，以获取该 Money Movement 的 metadata.virtual_account，然后与获取账户交易记录交叉核对，筛选 credit_debit_type=credit 并匹配相同的 metadata.account_reference。对于与 CLABE 关联的 SPEI 贷记，请直接查询交易，并将 metadata.account_reference 与您自己维护的已发放 CLABE 映射表进行匹配 —— 此时没有 Money Movement 可查询。

批量处理： 通过报告生成 Money Movement 报告（CSV 使用 money_movement_mex_spei_csv_v1 或 money_movement_csv_v1，JSON 使用 money_movement_v1）和交易报告（CSV 使用 transactions_csv_v1，JSON 使用 account_transactions_v1），并将导出的行筛选为 currency = MXN。将所有 spei_credit 记录按 metadata.account_reference 分组 —— 无论该 CLABE 是常设的还是为单次 Direct Link 请求生成的，这种方式都同样适用。对于 Direct Link 的记录，可交叉核对 Money Movement 报告中的 metadata.virtual_account，以确认每笔贷记结算的是哪一次请求。

实时对账： 请通过通知与订阅订阅事件，而不是反复轮询。对于 Direct Link R2P SPEI，状态一旦变化，money_movements.status.completed（以及 .rejected / .failed）就会触发。与 CLABE 关联的 SPEI 贷记没有 Money Movement 可供发出状态事件 —— 请改用 accounts.balance.credit，并通过事件中的 metadata.account_reference 进行匹配。

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

墨西哥 PayIn 对账允许的操作

🔍 查询 — Money Movement

🔍 查询 — 交易

🔑 报告

说明： 按状态、外部 ID、目标 Cobre Balance 或日期范围按需查询 Direct Link R2P SPEI 的 PayIn。不适用于与 CLABE 关联的 SPEI 贷记。

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

📘 了解更多：

🔗 获取所有 Money Movement

🔗 获取一个 Money Movement

如何开始

始终按 account_reference 对账 spei_credit 交易

无论收款是否经过 Money Movement，这是唯一保证存在的字段。

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

Direct Link R2P SPEI 会创建；与 CLABE 关联的 SPEI 贷记不会。对于 Direct Link，交易上的 account_reference 与 Money Movement 上的 virtual_account 相匹配。

在 Direct Link 的 PayIn 上始终提供 external_id

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

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

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

将退款作为关联的 spei_return / spei_debit 对进行跟踪

留意引用了此前已完成 PayIn 贷记的后续 spei_debit 交易。

使用此 API 后的预期结果

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

被拒绝或失败的 Direct Link PayIn 不会产生任何影响余额的交易。与 CLABE 关联的 SPEI 贷记则完全不经历这一生命周期。

每一笔 spei_credit 都按 account_reference 对账

对于 Direct Link，该值是 Money Movement 动态生成的 virtual_account；对于常设 CLABE，则是该 CLABE 本身。

已退款的 PayIn 会体现为关联的 spei_return / spei_debit 对

某个期间的对账需要同时考虑原始贷记以及任何后续的退款扣记 —— 与原始贷记不同，退款的两笔交易都带有 money_movement_id。

墨西哥 PayIn 对账

Money Movement 与交易#

墨西哥的贷记交易类型#

与 CLABE 关联的 SPEI 贷记不会创建 Money Movement#

PayIn 生命周期与余额影响#

退款同样会影响对账#

对账墨西哥的 PayIn#

墨西哥 PayIn 对账允许的操作#

如何开始#

使用此 API 后的预期结果#

Money Movement 与交易

墨西哥的贷记交易类型

与 CLABE 关联的 SPEI 贷记不会创建 Money Movement

PayIn 生命周期与余额影响

退款同样会影响对账

对账墨西哥的 PayIn

墨西哥 PayIn 对账允许的操作

如何开始

使用此 API 后的预期结果