资金流动

什么是资金流动？

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

从集成角度来看，资金流动 API 为您提供：

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

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

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

异步处理

审批（双人复核 Maker–Checker）

失败与拒绝

退款（仅限墨西哥）

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

核心概念

1）单一对象，多种支付通道

一个资金流动可由多种支付通道承载，但您始终与相同的资源结构和生命周期进行交互。支付通道通常通过其元数据和/或您所参考的具体指南来标识（例如 SPEI 出款、Bre-B 出款、Checkout 收款等）。

2）异步设计

资金流动采用异步处理方式：从初始状态开始，随着 Cobre 及下游系统确认执行而逐步演进。系统在"后台"持续更新状态，直至达到终态。

3）幂等性保障安全重试

API 支持可选的幂等性请求头，以防止意外重复提交。若您在有效时间窗口内使用相同的幂等键重试同一请求，Cobre 将返回原始资金流动记录，而不会新建一条。

通用资金流动状态机

每一笔资金流动均遵循相同的高级状态机。

可将其理解为三个阶段：

创建

处理中

终结

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

1）创建阶段

`initiated`

创建资金流动时，其初始状态为 initiated。
这意味着请求已被受理且流动记录已存在，但执行尚未推进。

2）处理阶段

`processing`

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

`pending_approval`（条件性）

部分资金流动在执行前需要明确审批（双人复核 Maker–Checker），这类流动将进入 pending_approval 状态。

若资金流动标记了 checker_approval = true，您的集成必须明确处理此状态：
可通过审批接口端点进行审批
或等待内部操作人员完成审批

3）终结阶段（终态）

资金流动将以以下终态之一结束：

`completed`

执行成功，流动已完结。

`canceled`

资金流动在完成前被取消（常见于审批过期或被取消，或计划/批量条目被上游取消）。

`failed`

因操作或平台层面原因导致处理失败。

`rejected`

支付通道、银行或用户层面的校验导致交易被拒绝，通常附有通道专属的拒绝原因码。

资金流动状态 `returned`（仅限墨西哥）

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

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

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

initiated → processing

initiated → pending_approval（若需审批）

pending_approval → processing（审批通过后）

processing → completed

processing → failed / rejected

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

pending_approval → canceled（若被取消/过期）

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

重要提示： 所有终态均为最终状态。资金流动一旦到达终态，将不再发生转换（但部分支付通道可能在先前完成后报告退款，以 returned 状态表示）。

集成模式（推荐）

第一步 — 创建资金流动

使用创建资金流动接口端点。

第二步 — 订阅资金流动状态变更事件

由于资金流动为异步处理，您必须订阅状态更新事件。

请避免轮询获取资金流动接口端点直至达到终态，这会产生不必要的请求。

请参阅通知与订阅

第三步 — 处理状态逻辑

若收到 pending_approval，请审批或等待审批

若收到 processing，继续监控

若为终态：

completed → 成功路径

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

rejected → 修正输入或视为业务失败场景

returned → 对账退款并更新账本

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

后续操作（选择您的支付通道/模式）

本页面为概念基础。如需实现细节，请前往：

出款通道

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

墨西哥：SPEI

美国：Fedwire

收款通道

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

墨西哥：Virtual CLABEs

跨通道执行模式

批量资金流动

资金流动调度器

审批（双人复核 Maker–Checker）

您将在所有上述场景中复用此处描述的相同生命周期模型。

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

资金流动类型	流向	来源	允许的来源类型	目标	允许的目标类型
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)
BRE-B	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
Fedwire	Push	account_id	cobre_balance	counterparty_id	business
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 在处理来源与目标对象组合方面的灵活性，确保了资金流动的无缝发起，能够满足广泛的交易需求。

自动通道路由

Fast Pay 转 ACH - 当哥伦比亚目标账户不支持 Fast Pay 时，Cobre 将自动通过 ACH 发送指令。查看可用于 Fast Pay 或 ACH 的哥伦比亚银行

Bre-B 转 Fast Pay - 所有超过 Bre-B 限额的 Bre-B 出款将自动通过 Fast Pay 路由（即 Cobre 最快的支付通道）

Bre-B 拆分付款 - Bre-B 出款可通过拆分付款功能在 Bre-B 通道进行多笔交易路由。

对账单中及付款时显示的名称

出款

支付通道（Rail）	对账单中的名称	启用该功能的 Cobre 功能
SPEI	客户的法定名称客户用户的法定名称	由 Cobre 客户拥有的成本中心账户（CECO）由 Cobre 客户用户拥有的成本中心账户（CECO）
Fast Pay	部分银行可能在描述中包含 Pexto Colombia SAS，但通常不会提供任何名称。视银行而定	不适用
ACH	部分银行可能在描述中包含 Pexto Colombia SAS，但通常不会提供任何名称。视银行而定	不适用
Bre-B	Pexto Colombia SAS	默认配置的 Cobre 法律实体名称
Fedwire	用于创建 FBO 的客户法定名称	Global Payments > 创建 Global Counterparty

收款

支付通道（Rail）	对账单中的名称	付款时显示	启用该功能的 Cobre 功能
PSE	银行通常不会在账单的描述中包含名称，但如果包含，通常是 Pexto Colombia SAS。	Pexto Colombia SAS 交易描述中客户的别名（商业名称）	默认配置的 Cobre 法律实体名称应客户请求配置客户别名
Nequi (R2P)	Pexto Colombia SAS 客户的法定名称+PXT	Pexto Colombia SAS 客户的法定名称	默认配置的 Cobre 法律实体名称应客户请求配置客户的法定名称
Nequi 直接扣款（Direct Debit）	Pexto Colombia SAS 客户的法定名称+PXT	Pexto Colombia SAS 客户的法定名称+PXT	默认配置的 Cobre 法律实体名称应客户请求配置客户的法定名称
Bancolombia	Pexto Colombia SAS	Pexto Colombia SAS	默认配置的 Cobre 法律实体名称应客户请求配置客户的法定名称
Bre-B（动态密钥 Dynamic Key）	Pexto Colombia SAS 客户的法定名称+PXT	Pexto Colombia SAS 客户的法定名称+PXT	默认配置的 Cobre 法律实体名称应客户请求配置客户别名
Cobre Keys	Pexto Colombia SAS 客户的法定名称+PXT 客户的客户名称	Pexto Colombia SAS 客户的法定名称+PXT 客户的客户名称	默认配置的 Cobre 法律实体名称应客户请求配置客户别名应客户请求配置客户的客户名称，以及 API 中的新字段
Transfer-In (ACH)	Pexto Pagos SAS	不适用	Transfer-In 默认配置
SPEI	成本中心账户（CECO）持有人	不适用	入驻（onboarding）期间开立的成本中心账户（CECO）

资金流动状态目录

请参阅资金流动状态

资金流动

什么是资金流动？#

核心概念#

1）单一对象，多种支付通道#

2）异步设计#

3）幂等性保障安全重试#

通用资金流动状态机#

1）创建阶段#

initiated#

2）处理阶段#

processing#

pending_approval（条件性）#

3）终结阶段（终态）#

completed#

canceled#

failed#

rejected#

资金流动状态 returned（仅限墨西哥）#

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

集成模式（推荐）#

第一步 — 创建资金流动#

第二步 — 订阅资金流动状态变更事件#

第三步 — 处理状态逻辑#

后续操作（选择您的支付通道/模式）#

出款通道#

收款通道#

跨通道执行模式#

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

对账单中及付款时显示的名称#

出款#

收款#

资金流动状态目录#

什么是资金流动？

核心概念

1）单一对象，多种支付通道

2）异步设计

3）幂等性保障安全重试

通用资金流动状态机

1）创建阶段

`initiated`

2）处理阶段

`processing`

`pending_approval`（条件性）

3）终结阶段（终态）

`completed`

`canceled`

`failed`

`rejected`

资金流动状态 `returned`（仅限墨西哥）

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

集成模式（推荐）

第一步 — 创建资金流动

第二步 — 订阅资金流动状态变更事件

第三步 — 处理状态逻辑

后续操作（选择您的支付通道/模式）

出款通道

收款通道

跨通道执行模式

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

对账单中及付款时显示的名称

出款

收款

资金流动状态目录