批量资金流动

批量资金划转允许您通过单次文件上传处理多笔资金划转，非常适合大批量 PayOuts 及操作性批处理场景。

批量功能常见用途包括：

执行大规模资金发放（例如：薪资发放、供应商付款、退款）。

通过在单次请求中提交多笔资金划转，减少 API 调用次数。

创建包含资金划转列表的 JSON 文件

第一步是创建您的 JSON 文件，指明需要处理的资金划转内容。

JSON 文件要求

输入 JSON 文件的关键规则：

载荷必须为 JSON 数组：以 [ 开头，以 ] 结尾。

每笔资金划转请求必须包含在 { } 中，并以逗号分隔。以下是示例格式：

[ 
   { 
       money_movement_request_1
   },
   {
       money_movement_request_2
   }
]

不允许注释（例如 // ...）。示例如下：

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",     //Comments are not allowed
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"MX Payment - Saldo Crobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    }
]

金额必须以最小货币单位发送（例如：100.00 MXN → 10000）。

输入文件的最大大小约为 4.7 MB。

支持的类型

批量资金划转支持两种资金划转对象类型。

使用已创建的 counterparty_id：以下示例展示了一个有效的 JSON 格式，包含两条创建资金划转请求体，可被批量资金划转接受：

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"SPEI Payment - Saldo Cobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    },
    {
        "amount":500,
        "source_id":"acc_aJmUHHWDOB",
        "destination_id":"cp_c0jhj7gn7v",
        "metadata":
        {
            "description":"ACH Payment Bancolombia",
        },
        "external_id":"BBM_32656"
    }
]

不使用已创建的 counterparty_id：该流程允许您通过在目标字段中直接包含创建 Counterparty 请求体详细信息来创建交易对手方。以下示例展示了一个有效的 JSON 格式，包含一笔带有有效交易对手方目标的 SPEI 资金划转，可被批量资金划转接受：

[
    {
        "amount": 1,
        "source_id": "acc_poyBrvkPRI",
        "destination":
        {
            "geo": "mex",
            "type": "clabe",
            "alias": "cccc",
            "metadata":
            {
                "account_number": "710969000037970288",
                "counterparty_fullname": "Company",
                "counterparty_id_type": "rfc",
                "counterparty_id_number": "ND"
            }
        },
        "metadata":
        {
            "description": "TEST PRO BMM",
            "reference": "009911"
        }
    }

]

支持的交易对手方

通过批量进行的 PayOuts 支持以下目标类型：

Colombia Payout Counterparties

Mexico Payout Counterparties

目标类型	交易对手方类型	支付通道
活期账户	`cc`	Fast Pay / ACH
储蓄账户	`ch`	Fast Pay / ACH
电子存款	`dp`	Fast Pay / ACH
BreB Key	`breb_key`	BreB / Fast Pay* / ACH*
Cobre Balance	`cobre_balance`	Fast Pay

批量中的 Counterparty 幂等性

批量资金划转流程在创建交易对手方之前，会通过验证其是否已被创建来确保幂等性。具体做法是通过拼接以下字段来进行幂等性校验：

交易对手方类型	拼接字段
`cc`	geo、type、account_number、beneficiary_institution、counterparty_fullname、counterparty_id_number、counterparty_id_type、counterparty_email 和 counterparty_phone
`ch`	geo、type、account_number、beneficiary_institution、counterparty_fullname、counterparty_id_number、counterparty_id_type、counterparty_email 和 counterparty_phone
`dp`	geo、type、account_number、beneficiary_institution、counterparty_fullname、counterparty_id_number、counterparty_id_type、counterparty_email 和 counterparty_phone
`cobre_balance`	geo、type、cobre_tag、counterparty_email、counterparty_fullname、counterparty_id_number、counterparty_id_type 和 counterparty_phone

授权工作流（可选）

您可以通过在请求头中将 checker_approval 标志设置为 true，将批量资金划转提交审批。

如果您选择提交批量审批，文件中的所有资金划转都将进入审批流程，若未出现验证或技术错误，这些资金划转将以 pending_approval 状态创建。

如需了解更多审批相关信息，请参阅批量资金划转审批。

批量生命周期

通过批量资金划转进行的 PayOuts 遵循以下简单生命周期：

1. 构建 JSON 文件
构建包含所有待处理资金划转的 JSON 文件。

2. 上传文件
上传文件以创建批量资金划转。

3. 验证流程
Cobre 对文件进行验证，并开始逐笔处理资金划转，同时跟踪批量处理状态（例如：验证中、处理中、已完成等）。

4. 资金划转创建
通过批量创建的资金划转将包含 batch_id（便于对账）。

5. 接收状态更新
通过查询接口端点和/或 Webhook 跟踪处理进度。

即使某笔资金划转遇到功能性错误，该资金划转对象仍可被创建，错误信息将体现在其状态描述中。

批量资金划转流程

平台将接收并验证包含多笔资金划转的文件。
验证通过后，将更新执行时间戳及付款总数。
随后，流程将执行文件中列出的所有资金划转，并通过更新执行时间和付款总数来完成整个流程。

批量资金划转状态

验证中（Validating）： 批量资金划转的初始状态，反映流程开始验证文件格式的时刻。

失败（Failed）： 表示验证流程遇到错误的状态。

处理中（Processing）： 表示文件已通过验证，文件中的每笔资金划转将被逐一处理的状态。

待审批（Pending Approval）： 表示文件正在等待审批的状态。

已取消（Canceled）： 表示批量资金划转流程已被取消的状态。

已完成（Completed）： 表示批量资金划转流程已完成的状态。

批量资金划转仅验证上传文件的格式。若发生功能性错误，资金划转对象仍将被创建，相关错误（来自错误字典）将包含在该资金划转的描述信息中。

支持的文件格式

随着我们持续完善批量资金划转流程以支持更多可用格式，目前允许以下格式：

文件格式	对象格式	最大大小
JSON	资金划转请求	4.7 Mb

批量资金划转的可执行操作

🔑 Create

🔍 Retrieval

👍 Approval

描述： 创建批量资金划转。
执行操作后的预期结果： 批量资金划转已在 Cobre 中创建。
📘 了解更多：

🔗 创建批量资金划转

如何开始

在开始之前，建议您先查阅以下注意事项。

使用此 API 前

Prepare your JSON file

创建一个包含所有资金划转请求的 JSON 数组。

遵循 JSON 文件要求规范。

确保每条记录使用已有的 destination_id 或内联的 destination 对象。

根据各交易对手方类型的拼接字段，合理运用 Counterparty 幂等性机制。

Ensure the correct money movement request

请确保资金划转字段填写正确：

请注意，来源与目标的组合必须构成有效的资金划转组合。

source_id 必须有效且已存在。

destination_id（如填写）必须有效且已存在。

metadata 中的字段需根据来源与目标的资金划转组合进行对应配置。

amount 为货币的最小单位（例如，100.00 MXN 应表示为 10000）。

输入 JSON 文件的最大大小约为 4.7 MB。

建议使用 external_id 将每笔付款关联至外部对象或业务流程。

建议实现 checker_approval 逻辑。

Send your Bulk money movement for approval (optional)

使用批量资金审批决策接口端点，对批量任务提交审批决策结果。

详情请参阅批量资金划转审批工作流。

Implement Webhooks to track Money Movement status

为及时掌握 PayOuts 交易的状态动态，我们强烈建议实现 Webhook。Webhook 可在付款发起、处理中、完成或失败时通知您的系统。同时，请订阅所需事件以接收交易借记和贷记的通知。

详情请参阅通知与订阅。

使用此 API 后的预期结果

Bulk process status updates

批量处理过程将依次经历 validating、processing 和 completed 等状态转换。

Reconcile using batch_id

通过批量任务创建的资金划转均包含 batch_id，可用于关联批次与各笔 PayOuts 结果。

Handle errors per Money Movement

部分资金划转可能因功能性要求未满足而失败。请使用查询接口端点和 Webhook 识别受影响的条目，并仅对其进行重试。

批量资金流动

创建包含资金划转列表的 JSON 文件#

JSON 文件要求#

支持的类型#

支持的交易对手方#

批量中的 Counterparty 幂等性#

授权工作流（可选）#

批量生命周期#

批量资金划转流程#

批量资金划转状态#

支持的文件格式#

批量资金划转的可执行操作#

如何开始#

使用此 API 前#

使用此 API 后的预期结果#