Cuentas Nombradas (MX)

🚧 Cuentas Nombradas estará disponible próximamente. Esta funcionalidad se encuentra actualmente en desarrollo y aún no está disponible. Mantente al tanto — actualizaremos esta página en cuanto sea lanzada. Mientras tanto, no dudes en contactar a tu Key Account Manager si tienes alguna pregunta.

Esta guía te lleva a través de la integración de API de extremo a extremo para Cuentas Nombradas en México — desde registrar a un comercio como Subclient, hasta crear una Cuenta Nombrada vinculada a su identidad, y operar esa cuenta usando los mismos endpoints de pago que ya utilizas hoy para pay-ins SPEI, pay-outs, CLABEs Virtuales y R2P SPEI.

Paso 1 — Registrar un Subclient

Antes de que se pueda crear cualquier cuenta bajo la identidad de un comercio, este debe estar registrado como Subclient y aprobar el proceso de screening de cumplimiento de Cobre.

Llama a POST /v1/subclients con la información legal, fiscal y de beneficiario final del comercio. El Subclient se crea inmediatamente en estado processing mientras el screening se ejecuta de forma asíncrona en segundo plano.

// 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"
    }
  ]
}

La respuesta devuelve el objeto Subclient en estado processing. Guarda el id — lo necesitarás en el Paso 2.

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

Rastrea el resultado del screening

El screening del Subclient es asíncrono. Suscríbete a los siguientes eventos mediante POST /v1/subscriptions para recibir el resultado sin necesidad de hacer polling:

Evento	Significado
`subclient.approved`	El screening fue aprobado — puedes continuar con el Paso 2
`subclient.rejected`	El screening fue rechazado — se debe crear un nuevo Subclient
`subclient.failed`	El screening presentó un error — se debe crear un nuevo Subclient

// 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"
}

Alternativamente, puedes hacer polling a GET /v1/subclients/{id} hasta que status.state deje de ser processing.

⚠️ No continúes con el Paso 2 hasta que el Subclient esté en estado approved. Intentar crear una cuenta con un Subclient en estado processing o rejected devolverá un error.

Paso 2 — Crear una Cuenta Nombrada

Una vez que el Subclient esté approved, crea una cuenta Cobre Balance y vincúlala al Subclient incluyendo el campo subclient en el cuerpo de la solicitud. Este es el único cambio respecto a la solicitud estándar POST /v1/accounts.

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

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

La respuesta devolverá la cuenta CLABE creada como es habitual

{
  "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"
}

Paso 3 — Operar la Cuenta Nombrada

A partir de este punto, la Cuenta Nombrada funciona exactamente igual que cualquier cuenta estándar de Cobre Balance en México. No se requieren cambios en tu integración existente — simplemente usa el acc_ ID de la Cuenta Nombrada como origen o destino en tus llamadas existentes.

Recibir pay-ins (créditos SPEI)

Comparte la CLABE del comercio con sus clientes. Las transferencias SPEI entrantes se acreditan a la Cuenta Nombrada como transacciones spei_credit, mostrando el nombre del comercio al remitente.

📘 Consulta Cobre Balance respaldados por CLABE para más detalles sobre la recepción de transferencias SPEI.

Enviar pay-outs (débitos SPEI)

Inicia transferencias SPEI desde la Cuenta Nombrada utilizando el endpoint estándar de money movements. El nombre del comercio se muestra al beneficiario en el registro SPEI.

📘 Consulta SPEI para más detalles.

Crear CLABEs Virtuales

Genera CLABEs de referencia adicionales vinculadas a la Cuenta Nombrada para conciliación o flujos de cobro multi-producto. Todas las CLABEs Virtuales heredan la identidad nombrada del comercio en SPEI.

📘 Consulta Referencia de Cuenta – CLABEs Virtuales para más detalles.

Solicitud de Pago – SPEI (R2P SPEI)

Inicia solicitudes R2P SPEI desde la Cuenta Nombrada. El nombre del comercio se muestra al pagador como el originador del cobro.

📘 Consulta Request to Pay (R2P) para más detalles.

Resumen

Paso	Acción	Endpoint
1a	Registrar al comercio como Subclient	`POST /v1/subclients`
1b	Rastrear el resultado del screening	webhook `subclient.approved` o `GET /v1/subclients/{id}`
2a	Crear una Cuenta Nombrada vinculada al Subclient aprobado	`POST /v1/accounts` con el campo `subclient`
2b	Esperar a que se asigne la CLABE	webhook `account.connected` o `GET /v1/accounts/{id}`
3	Operar normalmente — pay-ins, pay-outs, CLABEs Virtuales, R2P SPEI	Endpoints existentes, sin cambios necesarios

Acciones permitidas en las Cuentas Nombradas

🧾 Registrar un Subclient

🔎 Rastrear el screening del Subclient

🏦 Crear una Cuenta Nombrada

🔍 Consultar una Cuenta Nombrada

💸 Operar la Cuenta Nombrada

Descripción: Antes de crear una Cuenta Nombrada, el comercio debe registrarse como Subclient con su información legal, fiscal, de domicilio, beneficiario final y representante legal.

Qué esperar después de la acción: Se crea un Subclient en estado processing mientras Cobre ejecuta el screening de cumplimiento de forma asíncrona.

📘 Aprende más: 🔗 Crear un Subclient — No pude confirmar este ID en la documentación en español, ya que el endpoint aún no aparece en el índice (probablemente por no estar publicado). Te recomiendo verificarlo directamente en Apidog.

Cómo empezar

Antes de comenzar, revisa las siguientes consideraciones.

Antes de usar esta API

Confirma la disponibilidad de Cuentas Nombradas

Confirma la disponibilidad con tu Key Account Manager antes de iniciar la integración.

Prepara la información del comercio

Recopila la información legal, fiscal, de domicilio, sitio web, industria, beneficiario final y representante legal del comercio antes de crear el Subclient.

Configura los webhooks

Expón un endpoint de webhook HTTPS seguro y suscríbete a los eventos de screening del Subclient. Esto permite que tu sistema reaccione ante subclient.approved, subclient.rejected y subclient.failed sin necesidad de hacer polling.

Crea y aprueba el Subclient

Llama a POST /v1/subclients y espera hasta que el Subclient alcance el estado approved antes de crear la Cuenta Nombrada.

Crea la Cuenta Nombrada

Llama a POST /v1/accounts usando el proveedor de Cobre Balance para México e incluye el ID del Subclient aprobado en el campo subclient.

Opera con los endpoints existentes

Una vez que la cuenta esté lista, usa el acc_ ID de la Cuenta Nombrada en tus flujos existentes de pay-in SPEI, pay-out SPEI, CLABE Virtual y R2P SPEI.

Qué esperar después de usar esta API

Se realiza el screening de la identidad del comercio

El comercio está representado por un Subclient y debe aprobar el screening de cumplimiento de Cobre antes de que se pueda crear una Cuenta Nombrada.

Se crea una Cuenta Nombrada

La cuenta se vincula al Subclient aprobado y devuelve la misma estructura de objeto de cuenta utilizada por las cuentas Cobre Balance.

La identidad del comercio se muestra en los flujos SPEI

La identidad del comercio se utiliza al operar la Cuenta Nombrada en los flujos de pago y cobro soportados en México.

Tu integración existente sigue siendo reutilizable

Después de la configuración, continúa usando los mismos endpoints de Cobre para pay-ins, pay-outs, CLABEs Virtuales y R2P SPEI.

Cuentas Nombradas (MX)

Paso 1 — Registrar un Subclient#

Rastrea el resultado del screening#

Paso 2 — Crear una Cuenta Nombrada#

Paso 3 — Operar la Cuenta Nombrada#

Recibir pay-ins (créditos SPEI)#

Enviar pay-outs (débitos SPEI)#

Crear CLABEs Virtuales#

Solicitud de Pago – SPEI (R2P SPEI)#

Resumen#

Acciones permitidas en las Cuentas Nombradas#

Cómo empezar#

Antes de usar esta API#

Qué esperar después de usar esta API#

Paso 1 — Registrar un Subclient

Rastrea el resultado del screening

Paso 2 — Crear una Cuenta Nombrada

Paso 3 — Operar la Cuenta Nombrada

Recibir pay-ins (créditos SPEI)

Enviar pay-outs (débitos SPEI)

Crear CLABEs Virtuales

Solicitud de Pago – SPEI (R2P SPEI)

Resumen

Acciones permitidas en las Cuentas Nombradas

Cómo empezar

Antes de usar esta API

Qué esperar después de usar esta API