资金流动

什么是资金流动（Money Movement）？

Money Movement 是 Cobre 的统一对象，用于表示资金进出余额的完整生命周期——无论该流动是收款（payin）还是付款（payout），也无论底层支付通道或地理位置如何。

从集成角度来看，Money Movement API 为您提供：

统一接口，用于创建和追踪资金操作

一致的生命周期与状态模型

处理以下场景的标准模式：

异步处理

审批（双人复核，Maker–Checker）

失败与拒绝

退款（仅限墨西哥）

本指南为概念性介绍；各子章节（SPEI、Bre-B、Checkout、Direct Link、Scheduler、Bulk 等）将描述各支付通道的特定字段与行为。

核心概念

1）单一对象，多条通道

Money Movement 可由多条支付通道支撑，但您始终与相同的资源结构和生命周期进行交互。支付通道通常在其元数据中体现，或体现在您所遵循的具体指南中（例如 SPEI 付款、Bre-B 付款、Checkout 收款等）。

2）异步设计

Money Movement 以异步方式处理：它从初始状态开始，随着 Cobre 及下游系统确认执行而逐步演变。系统在"后台"持续更新状态，直至达到终态。

3）幂等性以确保安全重试

API 支持可选的幂等性请求头，以防止意外重复提交。如果您在相关时间窗口内使用相同的幂等键重试同一请求，Cobre 将返回原始 Money Movement，而不会再创建一个新的。

通用 Money Movement 状态机

每个 Money Movement 均遵循相同的高层级状态机。

可将其视为三个阶段：

创建

处理中

终结

以下是横向生命周期，适用于墨西哥和哥伦比亚的收款与付款。

1）创建阶段

`initiated`

当您创建一个 Money Movement 时，它从 initiated 状态开始。
这意味着请求已被接受且流动记录已存在，但尚未开始执行。

2）处理阶段

`processing`

Cobre 开始执行时，Money Movement 进入 processing 状态。
此时，该流动正在进行中，应视为非终态。

`pending_approval`（条件性）

部分 Money Movement 在执行前需要显式审批（双人复核，Maker–Checker），这些流动将进入 pending_approval 状态。

如果该资金流动标记了 checker_approval = true，您的集成必须明确处理此状态：
通过审批接口端点进行审批
或等待其保持待审批状态，直到您的内部操作人员批准

3）终结阶段（终态）

Money Movement 将以以下终态之一结束：

`completed`

执行成功，流动已终结。

`canceled`

Money Movement 在完成前被取消（常见于审批超时或被取消，或计划/批量条目被上游取消）。

`failed`

因运营或平台级原因导致处理失败。

`rejected`

拒绝意味着支付通道、银行或用户级验证导致交易被拒绝，通常附有通道特定的原因码。

Money movement 状态 `returned`（仅限墨西哥）

退款意味着该流动最初执行成功，但随后被交易对手方/收款方退回（例如，收款方退回了付款）。
示例原因：R008 付款被收款方退回。

状态流转（如何理解生命周期）

以下为概念性状态图（简化版）：

initiated → processing

initiated → pending_approval（如需审批）

pending_approval → processing（审批通过后）

processing → completed

processing → failed / rejected

processing → returned（完成后的退款路径）

pending_approval → canceled（如被取消或超期）

initiated → canceled（如在执行前被取消）

重要提示： 所有终态均为最终状态。一旦 Money Movement 达到终态，将不再发生状态流转（但某些通道可能在之前完成后报告退款，以 returned 表示）。

集成模式（推荐）

步骤 1 — 创建 Money Movement

使用创建 Money Movement 接口端点。

步骤 2 — 订阅 Money Movement 状态变更事件

由于 Money Movement 是异步的，您必须订阅状态更新事件。

请避免轮询获取 Money Movement 接口端点直至达到终态，因为这会产生不必要的请求。

参见通知与订阅

步骤 3 — 处理状态逻辑

收到 pending_approval 时，进行审批或等待审批

收到 processing 时，继续监控

收到终态时：

completed → 成功路径

failed → 评估错误码并制定重试策略

rejected → 修正输入或视为业务失败案例

returned → 对账退款并更新您的账本

canceled → 视为无操作或用户主动取消

后续步骤（选择您的通道/模式）

本页为概念基础。如需实现细节，请参阅：

付款通道

哥伦比亚：Fast Pay & ACH、Bre-B

墨西哥：SPEI

收款通道

哥伦比亚：Checkout、Cobre Keys、Direct Link

墨西哥：Virtual CLABEs

跨通道执行模式

批量 Money Movements

Money Movement 调度器

审批（双人复核，Maker–Checker）

以上所有场景均复用本文所述的相同生命周期模型。

通过 API 发起资金流动时，您的输入应如下所示：

Money Movement 类型	流向	来源	允许的来源类型	目标	允许的目标类型
SPEI	Push	account_id	clabe	counterparty_id or account_id	clabe or spei_card
FAST PAY	Push	account_id	cobre_balance	counterparty_id or account_id	checking(cc), saving (ch), cobre_balance, electronic deposit (dp)
ACH	Push	account_id	checking(cc), saving (ch) or cobre_balance	counterparty_id or account_id	checking(cc), saving (ch) or electronic deposit (dp)
BREB	Push	account_id	cobre_balance	counterparty_id	Breb-B (breb_key)
GLOBAL	Push	account_id	cobre_balance	counterparty_id	global_deposit_le or global_deposit_np
R2P Direct Dynamic Key	Pull	counterparty_id	r2p or r2p_breb	account_id	cobre_balance
R2P Direct Link	Pull	counterparty_id	r2p	account_id	cobre_balance
DIRECT DEBIT	Pull	counterparty_id	checking(cc), saving (ch) or cobre_balance	account_id	cobre_balance

API 在处理来源与目标对象组合方面的灵活性，确保了资金流动的无缝发起，可满足多样化的交易需求。

Money Movement 状态目录

状态	代码	描述
initiated	NA	NA
processing	NA	NA
completed	NA	NA
pending_approval	NA	NA
canceled	NA	NA
failed	F001	支付处理失败，请重试
failed	F002	NSF - 指定账户余额不足
failed	F003	R2P 支付链接已过期
failed	F004	已达到每日交易金额上限
failed	F005	金额超过单笔交易最高限额
failed	F098	当前无法处理该资金划转
failed	F099	当前无法处理该资金划转
rejected	R000	交易被拒绝
rejected	R001	账户未激活或已被冻结
rejected	R002	账户与所提供的身份信息不符
rejected	R004	身份证件无效
rejected	R005	账户不存在
rejected	R006	账户号码无效
returned	R008	付款被收款方退回
rejected	R009	超过最高允许金额
rejected	R010	账户未获授权进行扣款
rejected	R011	账户类型无效
rejected	R012	用户已放弃该交易
rejected	R015	账户未获授权接收入账
rejected	R016	付款因超时被拒绝
rejected	R017	付款因密钥过期被拒绝
rejected	R018	付款因密钥无效被拒绝
rejected	R019	付款因金额不正确被拒绝
rejected	R020	付款因用户身份验证失败被拒绝
rejected	R021	付款方账户余额不足
rejected	R023	付款已被用户取消
rejected	R024	超过最大允许交易笔数
rejected	R025	缺少必要信息
rejected	R026	付款因银行服务不可用被拒绝
rejected	R027	账户超过单笔交易最高限额
rejected	R034	账户已注销
rejected	R081	交易对手方注册已过期
rejected	R082	交易对手方注册已被取消
rejected	R084	交易对手方注册已被拒绝
rejected	R085	银行处理错误

资金流动

什么是资金流动（Money Movement）？#

核心概念#

1）单一对象，多条通道#

2）异步设计#

3）幂等性以确保安全重试#

通用 Money Movement 状态机#

1）创建阶段#

initiated#

2）处理阶段#

processing#

pending_approval（条件性）#

3）终结阶段（终态）#

completed#

canceled#

failed#

rejected#

Money movement 状态 returned（仅限墨西哥）#

状态流转（如何理解生命周期）#

集成模式（推荐）#

步骤 1 — 创建 Money Movement#

步骤 2 — 订阅 Money Movement 状态变更事件#

步骤 3 — 处理状态逻辑#

后续步骤（选择您的通道/模式）#

付款通道#

收款通道#

跨通道执行模式#

通过 API 发起资金流动时，您的输入应如下所示：#

Money Movement 状态目录#

什么是资金流动（Money Movement）？

核心概念

1）单一对象，多条通道

2）异步设计

3）幂等性以确保安全重试

通用 Money Movement 状态机

1）创建阶段

`initiated`

2）处理阶段

`processing`

`pending_approval`（条件性）

3）终结阶段（终态）

`completed`

`canceled`

`failed`

`rejected`

Money movement 状态 `returned`（仅限墨西哥）

状态流转（如何理解生命周期）

集成模式（推荐）

步骤 1 — 创建 Money Movement

步骤 2 — 订阅 Money Movement 状态变更事件

步骤 3 — 处理状态逻辑

后续步骤（选择您的通道/模式）

付款通道

收款通道

跨通道执行模式

通过 API 发起资金流动时，您的输入应如下所示：

Money Movement 状态目录