Gestión de Subclientes - Payins Colombia

🚧 Este flujo está en desarrollo activo.

Los Subclientes son el modelo de Cobre para identificar al comercio final detrás de un agregador: una identidad registrada, revisada antes de poder operar, que viaja con cada transacción. Esta guía cubre la primera implementación de ese modelo en Colombia: asociar un Subcliente a un Payin Request to Pay (R2P) PSE, para que se pueda identificar al comercio final detrás de la transacción.

Cómo funciona

Registra el Subcliente — Llama a POST /v1/subclients con la información legal, fiscal y de beneficiarios finales del comercio. Estos datos pasan por un proceso de revisión asíncrono.

Espera la aprobación — El Subcliente inicia en processing y pasa a approved (o rejected/failed) cuando termina la revisión.

Crea el Movimiento de Dinero R2P PSE — Una vez approved, envía el id del Subcliente en el nuevo campo subclient_id del nivel raíz al llamar a POST /v1/money_movements para un Payin r2p_pse.

Requisitos previos

Una cuenta Cobre Balance en Colombia para recibir los fondos.

Una Contraparte de tipo r2p que represente al pagador (consulta Crear una Contraparte).

Acceso a Crear un Subclient y Crear un Movimiento de Dinero.

Guía paso a paso

Paso 1 – Registra el Subcliente

Llama al POST Crear un Subclient

El Subcliente se crea de inmediato en estado processing mientras la revisión corre en segundo plano:

Conserva el id devuelto (sc_...): es el subclient_id que usarás en el Paso 3.

Paso 3 – Espera la revisión del Subcliente

La revisión del Subcliente es asíncrona:

El Subcliente inicia en processing.

Cobre revisa la información enviada.

El Subcliente pasa a approved o rejected. failed se devuelve en casos excepcionales en los que ocurre un error técnico.

Consulta Obtener un Subclient o suscríbete a los eventos subclient.processing, subclient.approved, subclient.rejected y subclient.failed — consulta notificaciones de Subclientes — para seguir el cambio de estado.

Un Subcliente rejected no puede reenviarse: crea un nuevo registro de Subcliente con la información corregida.

Un Subcliente solo necesita registrarse y aprobarse una vez; después puede reutilizarse en varios Movimientos de Dinero R2P PSE.

Paso 4 – Crea el Movimiento de Dinero R2P PSE con `subclient_id`

Con el Subcliente en approved, crea el Payin R2P PSE llamando a Crear un Movimiento de Dinero como lo harías normalmente para r2p_pse (consulta Direct Link para el detalle del riel) e incluye el nuevo campo subclient_id de nivel raíz junto a source_id, destination_id, amount y metadata.

📌

subclient_id es opcional por defecto, pero obligatorio para clientes agregadores/PSP una vez que este requisito esté habilitado en tu cuenta.

Si eres un agregador/PSP, omitir subclient_id — o enviar uno inválido o que no exista — hace que la solicitud de Movimiento de Dinero falle con el error MM034. En ese caso no se crea ningún Movimiento de Dinero.

Si tu cliente no es un PSP, subclient_id sigue siendo totalmente opcional en los Movimientos de Dinero r2p_pse.

Conceptos clave y terminología

Subcliente: registro de identidad de un comercio creado mediante POST /subclients o el módulo Subclientes del Portal. Debe estar approved antes de que su id pueda usarse como subclient_id en un Movimiento de Dinero.

subclient_id: nuevo campo de nivel raíz en POST /money_movements. En los Payins r2p_pse de Colombia, vincula el Movimiento de Dinero con un Subcliente aprobado previamente. Obligatorio para clientes agregadores/PSP una vez habilitado.

Agregadores/PSP (Payment Service Provider): un cliente que usa los servicios de Cobre para ofrecerlos a sus propios clientes.

Consideraciones

Un Subcliente debe estar approved antes de que su id pueda usarse como subclient_id.

Un Subcliente rejected no puede reenviarse; crea uno nuevo.

Una vez approved, un Subcliente puede reutilizarse en varios Movimientos de Dinero R2P PSE.

Hoy este requisito solo aplica a Payins r2p_pse en Colombia.

Preguntas frecuentes

¿Debo crear un Subcliente nuevo para cada Movimiento de Dinero R2P PSE?
No. Una vez approved, un Subcliente puede reutilizarse en tantos Movimientos de Dinero R2P PSE como necesites.

¿Qué pasa si omito subclient_id y soy un PSP/agregador?
La solicitud de Movimiento de Dinero falla con el error MM034 y no se crea ningún Movimiento de Dinero.

¿Este flujo está disponible en el Portal?
La creación del Subcliente está disponible, pero la creación del Movimiento de Dinero de este flujo hoy es solo por API.

¿subclient_id es obligatorio en otros rieles R2P (Nequi, Bancolombia, Bre-B) o en Payouts?
No. Hoy esto aplica solo a Payins r2p_pse en Colombia.

Movimientos asociados al Subcliente

Gestión de Subclientes - Payins Colombia#

Cómo funciona#

Requisitos previos#

Guía paso a paso#

Paso 1 – Registra el Subcliente#

Paso 3 – Espera la revisión del Subcliente#

Paso 4 – Crea el Movimiento de Dinero R2P PSE con subclient_id#

Conceptos clave y terminología#

Consideraciones#

Preguntas frecuentes#

Gestión de Subclientes - Payins Colombia

Cómo funciona

Requisitos previos

Guía paso a paso

Paso 1 – Registra el Subcliente

Paso 3 – Espera la revisión del Subcliente

Paso 4 – Crea el Movimiento de Dinero R2P PSE con `subclient_id`

Conceptos clave y terminología

Consideraciones

Preguntas frecuentes