子客户管理 - 哥伦比亚 Payins

🚧 此流程正在积极开发中。

子客户是 Cobre 用来识别聚合商背后最终商户的模型：一份在运营前经过审核的注册身份，并随每笔交易传递。本指南介绍该模型在哥伦比亚的首次实现：将 子客户 关联到 Request to Pay (R2P) PSE Payin，以便识别交易背后的最终商户。

工作方式

注册子客户 — 进入子客户模块并点击 Create subclient，填写表单，提交商户的法律、税务和最终受益所有人信息。这些资料会进入异步审核。

等待批准 — 子客户初始状态为 processing，审核完成后变为 approved（或 rejected/failed）。

创建 R2P PSE 资金流动 — 状态为 approved 后，在调用 POST /v1/money_movements 创建 r2p_pse Payin 时，将子客户的 id 作为新的根级字段 subclient_id 传入。

前提条件

一个用于收款的哥伦比亚 Cobre Balance 账户。

一个代表付款方的 r2p 类型交易对手方（请参阅创建 Counterparty）。

可访问创建子客户和创建资金流动。

分步指南

步骤 1 – 打开子客户模块

在左侧边栏中，进入 子客户。

Captura de pantalla 2026-08-25 a la(s) 12.35.02 p.m..png

此页面列出您已注册的每个子客户，包含：

Business name

Document（税号）

Status — Enabled、Processing、Rejected 或 Failed

Registration ID — 子客户在 Cobre 系统中的唯一标识（sc_...）

Created at

步骤 2 – 注册新的子客户

点击 + Create subclient。向导有四个页签：Company → Representatives → Beneficiaries → Summary。

2.1 Company

输入商户的企业资料：

Captura de pantalla 2026-08-25 a la(s) 12.40.42 p.m..png

Name / Business name

Identifier — 子客户的商业名称。

Document type 和 Document number（例如 NIT）

Email、Phone、Website

Industry

Incorporation date 和 Country of incorporation

Address — Street、City、State/Province、Postal code、Country

Country of operation

点击 Continue。

2.2 Representatives

登记公司的法定代表人（最多 20 位）：

Captura de pantalla 2026-08-25 a la(s) 12.41.19 p.m..png

每位代表人需要：First name(s)、Last name、Document type、Document number、Date of birth 和 Nationality（每人可添加多个国籍）。使用 Add representative 添加更多条目。

点击 Continue。

2.3 Beneficiaries (UBOs)

登记每一名直接或间接持有公司 25% 或以上 权益的最终受益所有人（最多 4 位）：

Captura de pantalla 2026-08-25 a la(s) 12.41.41 p.m..png

字段与 Representatives 步骤相同：First name(s)、Last name、Document type、Document number、Date of birth、Nationality。使用 Add beneficiary 添加更多条目。

点击 Continue。

2.4 Summary

提交前核对全部信息：

Captura de pantalla 2026-08-25 a la(s) 12.42.08 p.m..png

每个部分（Company、Legal Representative、UBOs）都有 Edit 入口，可在提交前修改。准备好后，点击 Create subclient。

子客户会立即以 processing 状态创建，审核在后台进行：

请保留返回的 id（sc_...）— 这就是您在步骤 3 中要使用的 subclient_id。

步骤 3 – 等待子客户审核

子客户审核是异步的：

子客户初始状态为 processing。

Cobre 审核所提交的信息。

子客户变为 approved 或 rejected。出现技术错误的特殊情况下会返回 failed。

rejected 的子客户不能重新提交 — 请使用更正后的信息创建新的子客户记录。

子客户只需注册并获批一次，之后可在多笔 R2P PSE 资金流动中重复使用。

步骤 4 – 使用 `subclient_id` 创建 R2P PSE 资金流动

子客户状态为 approved 后，按创建 r2p_pse 的常规方式调用创建资金流动（通道细节请参阅 Direct Link），并包含新的 subclient_id 字段。

📌

subclient_id 默认可选，但在您的账户启用此要求后，对聚合商/PSP 客户为必填。

如果您是聚合商/PSP，遗漏 subclient_id，或发送无效、不存在的值，资金流动请求会以错误 MM034 失败。此时不会创建资金流动。

如果您的客户不是 PSP，r2p_pse 资金流动上的 subclient_id 仍然完全可选。

核心概念和术语

子客户：通过 POST /subclients 或门户中的子客户模块创建的商户身份记录。其 id 用作资金流动的 subclient_id 之前，状态必须为 approved。

subclient_id：POST /money_movements 上新的根级字段。对于哥伦比亚的 r2p_pse Payin，它将资金流动关联到先前已获批的子客户。启用后，对聚合商/PSP 客户为必填。

聚合商/PSP（Payment Service Provider）：使用 Cobre 服务并向自己的客户提供这些服务的客户。

注意事项

子客户必须为 approved，其 id 才能用作 subclient_id。

rejected 的子客户不能重新提交 — 请创建一个新的。

一旦 approved，子客户可在多笔 R2P PSE 资金流动中重复使用。

目前此要求仅适用于哥伦比亚的 r2p_pse Payin。

常见问题

是否需要为每一笔 R2P PSE 资金流动创建一个新的子客户？
不需要。一旦 approved，同一个子客户可以用于任意多笔 R2P PSE 资金流动。

如果我是 PSP/聚合商并遗漏了 subclient_id，会发生什么？
资金流动请求会以错误 MM034 失败，并且不会创建资金流动。

此流程可以在门户中完成吗？
子客户创建可用，但此流程的资金流动创建目前仅可通过 API 完成。

其他 R2P 通道（Nequi、Bancolombia、Bre-B）或 Payout 是否也要求 subclient_id？
不要求。目前仅适用于哥伦比亚的 r2p_pse Payin。

子客户管理 - 哥伦比亚 Payins

工作方式#

前提条件#

分步指南#

步骤 1 – 打开子客户模块#

步骤 2 – 注册新的子客户#

2.1 Company#

2.2 Representatives#

2.3 Beneficiaries (UBOs)#

2.4 Summary#

步骤 3 – 等待子客户审核#

步骤 4 – 使用 subclient_id 创建 R2P PSE 资金流动#

核心概念和术语#

注意事项#

常见问题#

工作方式

前提条件

分步指南

步骤 1 – 打开子客户模块

步骤 2 – 注册新的子客户

2.1 Company

2.2 Representatives

2.3 Beneficiaries (UBOs)

2.4 Summary

步骤 3 – 等待子客户审核

步骤 4 – 使用 `subclient_id` 创建 R2P PSE 资金流动

核心概念和术语

注意事项

常见问题