命名账户（MX）

🚧 命名账户即将推出。此功能目前正在开发中，尚未可用。敬请关注——一经发布，我们将立即更新本页。在此期间，如有任何问题，请随时联系您的关键客户经理。

本指南将带您完成墨西哥命名账户的端到端 API 集成：从将商户注册为子客户（Subclient），到创建与其身份关联的命名账户，再到使用您目前已用于 SPEI 收款、付款、虚拟 CLABE 和 R2P SPEI 的相同支付端点来操作该账户。

在按照本指南操作之前，请先阅读命名账户概述，以了解关键概念和限制。

步骤 1 — 注册子客户

在商户身份下创建任何账户之前，必须先将该商户注册为子客户，并通过 Cobre 的合规审查。

调用 POST /v1/subclients，提交商户的法律、税务和受益所有权信息。子客户会立即以 processing（处理中）状态创建，同时合规审查在后台异步进行。

// POST /v1/subclients
// Headers: Authorization: Bearer sk_live_... | client_id: cli_xxx123

{
  "legal_name": "Merchant Co. S.A. de C.V.",
  "short_name": "MerchantCo",
  "id_type": "rfc",
  "id_number": "MER900101ABC",
  "email": "contacto@merchantco.mx",
  "phone": "+525512345678",
  "website": "https://www.merchantco.mx",
  "industry": "internet_marketplace",
  "date_of_incorporation": "2015-03-20",
  "country_of_incorporation": "mex",
  "address": {
    "street": "Av. Insurgentes Sur 1234",
    "city": "Ciudad de Mexico",
    "state": "CDMX",
    "postal_code": "03100",
    "country": "mex"
  },
  "ubos": [
    {
      "first_name": "Juan",
      "last_name": "Perez",
      "id_type": "rfc",
      "id_number": "PELJ800101ABC",
      "nationalities": ["mex","col"],
      "date_of_birth": "1975-08-08"
    }
  ],
  "legal_representatives": [
    {
      "first_name": "María",
      "last_name": "García Torres",
      "id_type": "rfc",
      "id_number": "GATM850101XYZ",
      "nationalities": ["mex","col"],
      "date_of_birth": "1985-10-28"
    }
  ]
}

重要：请提供 UBO 和法定代表人的完整法定姓名。姓名不完整可能会导致子客户在审查过程中因姓名部分匹配而被拒绝。

响应会返回处于 processing 状态的子客户对象。请保存其 id——您将在步骤 2 中使用该值。

{
  "id": "sc_4xKmN8pQrLvW2T",
  "object": "subclient",
  "status": {
    "state": "processing"
  },
  "legal_name": "Merchant Co. S.A. de C.V.",
  "short_name": "MerchantCo",
  ...
}

跟踪审查结果

子客户审查是异步进行的。通过 POST /v1/subscriptions 订阅以下事件，无需轮询即可接收审查结果：

事件	含义
`subclient.approved`	审查通过——您可以继续执行步骤 2
`subclient.rejected`	审查未通过——必须创建新的子客户
`subclient.failed`	审查过程中发生错误——必须创建新的子客户

// POST /v1/subscriptions

{
  "events": ["subclient.processing", "subclient.approved", "subclient.rejected", "subclient.failed"],
  "description": "Named Accounts screening notifications",
  "url": "https://your-domain.com/webhooks/cobre",
  "event_signature_key": "your_secret_key"
}

或者，轮询 GET /v1/subclients/{id}，直到 status.state 不再为 processing。

⚠️ 在子客户状态变为 approved 之前，请勿继续执行步骤 2。尝试使用状态为 processing 或 rejected 的子客户创建账户将返回错误。

步骤 2 — 创建命名账户

子客户变为 approved 后，创建一个 Cobre Balance 账户，并在请求正文中传入 subclient 字段，将该账户与子客户关联。这是对标准 POST /v1/accounts 请求的唯一改动。

// POST /v1/accounts
// Headers: Authorization: Bearer sk_live_...

{
  "action": "create",
  "alias": "MerchantCo Principal",
  "provider_id": "pr_mex_cobre3",
  "subclient_id": "sc_4xKmN8pQrLvW2T"
}

响应将像往常一样返回已创建的 CLABE 账户。

{
  "id": "acc_9TuVwXyZaBcDeF",
  "object": "account",
  "status": {
    "state": "processing"
  },
  "subclient_id": "sc_4xKmN8pQrLvW2T",
  "alias": "MerchantCo Principal",
  "provider_id": "pr_mex_cobre3",
  "account_number": "703123456789012345",
  "created_at": "2026-06-01T11:00:00Z",
  "updated_at": "2026-06-01T11:00:00Z"
}

步骤 3 — 操作命名账户

从此刻起，命名账户的工作方式与墨西哥的任何标准 Cobre Balance 账户完全相同。您无需更改现有集成——只需在现有调用中，将命名账户的 acc_ ID 用作资金来源或目的地即可。

接收收款（SPEI 入账）

与商户的客户共享该商户的 CLABE。传入的 SPEI 转账将作为 spei_credit 交易记入命名账户，并向付款方显示商户名称。

📘 有关接收 SPEI 转账的完整详情，请参阅基于 CLABE 的账户 – Cobre Balances。

发送付款（SPEI 出账）

使用标准资金流动端点从命名账户发起 SPEI 转账。SPEI 记录会向收款方显示商户名称。

📘 有关完整详情，请参阅 SPEI 付款。

创建虚拟 CLABE

生成与命名账户关联的其他参考 CLABE，用于对账或多产品收款流程。所有虚拟 CLABE 都会在 SPEI 中继承商户的命名身份。

📘 有关完整详情，请参阅账户参考 – 虚拟 CLABE。

请求付款 – SPEI（R2P SPEI）

从命名账户发起 R2P SPEI 请求。付款方会看到商户名称作为收款发起方。

📘 有关完整详情，请参阅请求付款（R2P）SPEI。

总结

步骤	操作	端点
1a	将商户注册为子客户	`POST /v1/subclients`
1b	跟踪审查结果	`subclient.approved` Webhook 或 `GET /v1/subclients/{id}`
2a	创建与已获批子客户关联的命名账户	使用 `subclient` 字段调用 `POST /v1/accounts`
2b	等待分配 CLABE	`account.connected` Webhook 或 `GET /v1/accounts/{id}`
3	正常操作——收款、付款、虚拟 CLABE、R2P SPEI	使用现有端点，无需更改

命名账户允许执行的操作

🧾 注册子客户

🔎 跟踪子客户审查

🏦 创建命名账户

🔍 查询命名账户

💸 操作命名账户

说明： 创建命名账户之前，必须使用商户的法律、税务、地址、受益所有权和法定代表人信息，将该商户注册为子客户。

执行操作后的预期结果： 子客户以 processing 状态创建，同时 Cobre 在后台异步执行合规审查。

📘 了解更多： 🔗 创建子客户

如何开始

开始之前，请查看以下注意事项。

使用此 API 之前

确认命名账户可用性

开始集成之前，请与您的关键客户经理确认该功能是否可用。

准备商户信息

创建子客户之前，请收集商户的法律、税务、地址、网站、行业、受益所有人和法定代表人信息。

配置 Webhook

公开一个安全的 HTTPS Webhook 端点并订阅子客户审查事件。这样，您的系统无需轮询即可响应 subclient.approved、subclient.rejected 和 subclient.failed。

创建子客户并等待获批

调用 POST /v1/subclients，并等待子客户达到 approved 状态，然后再创建命名账户。

创建命名账户

使用墨西哥 Cobre Balance 提供商调用 POST /v1/accounts，并在 subclient 字段中包含已获批的子客户 ID。

使用现有端点进行操作

账户准备就绪后，在现有的 SPEI 收款、SPEI 付款、虚拟 CLABE 和 R2P SPEI 流程中使用命名账户的 acc_ ID。

使用此 API 后的预期结果

商户身份通过审查

商户由子客户表示，并且必须通过 Cobre 的合规审查，之后才能创建命名账户。

创建命名账户

该账户与已获批的子客户关联，并返回与 Cobre Balance 账户相同的账户对象结构。

SPEI 流程中显示商户身份

在受支持的墨西哥支付和收款流程中操作命名账户时，将使用该商户身份。

可继续复用现有集成

完成设置后，继续使用相同的 Cobre 端点执行收款、付款、虚拟 CLABE 和 R2P SPEI 操作。

命名账户（MX）

步骤 1 — 注册子客户#

跟踪审查结果#

步骤 2 — 创建命名账户#

步骤 3 — 操作命名账户#

接收收款（SPEI 入账）#

发送付款（SPEI 出账）#

创建虚拟 CLABE#

请求付款 – SPEI（R2P SPEI）#

总结#

命名账户允许执行的操作#

如何开始#

使用此 API 之前#

使用此 API 后的预期结果#

步骤 1 — 注册子客户

跟踪审查结果

步骤 2 — 创建命名账户

步骤 3 — 操作命名账户

接收收款（SPEI 入账）

发送付款（SPEI 出账）

创建虚拟 CLABE

请求付款 – SPEI（R2P SPEI）

总结

命名账户允许执行的操作

如何开始

使用此 API 之前

使用此 API 后的预期结果