Subclient Management - Payins Colombia

🚧 This flow is in active development.

Subclients are Cobre's model for identifying the end merchant behind an aggregator — a registered identity, screened before it can operate, that travels with every transaction. This guide covers the first Colombia implementation of that model: attaching a Subclient to a Request to Pay (R2P) PSE Payin, so the end merchant behind the transaction can be identified.

How It Works

Register the Subclient — Call POST /v1/subclients with the merchant's legal, tax, and beneficial ownership information. This data goes through an asynchronous screening process.

Wait for approval — The Subclient starts in processing and moves to approved (or rejected/failed) once screening completes.

Create the R2P PSE Money Movement — Once approved, pass the Subclient's id as the new root-level subclient_id field when calling POST /v1/money_movements for an r2p_pse Payin.

Prerequisites

A Cobre Balance account in Colombia to receive funds.

A Counterparty of type r2p representing the payer (see Create a Counterparty).

Access to Create a Subclient and Create a Money Movement.

Step-by-Step Guide

Step 1 – Open the Subclients module

In the left sidebar, go to Subclients.

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

This screen lists every Subclient you've registered, with:

Business name

Document (tax ID)

Status — Enabled, Processing, Rejected or Failed

Registration ID — the subclient's unique identifier (sc_...) in Cobre's system

Created at

Step 2 – Register a new Subclient

Click + Create subclient. The wizard has four tabs: Company → Representatives → Beneficiaries → Summary.

2.1 Company

Enter the merchant's business details:

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

Name / Business name

Identifier — Subclient commercial name.

Document type and Document number (e.g. NIT)

Email, Phone, Website

Industry

Incorporation date and Country of incorporation

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

Country of operation

Click Continue.

2.2 Representatives

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

For each representative: First name(s), Last name, Document type, Document number, Date of birth, and Nationality (you can add more than one nationality per person). Use Add representative for additional entries.

Click Continue.

2.3 Beneficiaries (UBOs)

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

Same fields as the Representatives step: First name(s), Last name, Document type, Document number, Date of birth, Nationality. Use Add beneficiary for additional entries.

Click Continue.

2.4 Summary

Review everything before submitting:

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

Each section (Company, Legal Representative, UBOs) has an Edit shortcut to fix anything before submitting. When ready, click Create subclient.

The Subclient is created immediately in processing status while screening runs in the background:

Keep the returned id (sc_...) — this is the subclient_id you'll use in Step 3.

Step 3 – Wait for Subclient screening

Subclient screening is asynchronous:

The Subclient starts in processing.

Cobre reviews the submitted information.

The Subclient moves to approved or rejected. failed is returned in exceptional cases where a technical error occurs.

A rejected Subclient cannot be resubmitted — create a new Subclient record with corrected information instead.

A Subclient only needs to be registered and approved once — it can then be reused across multiple R2P PSE Money Movements.

Step 4 – Create the R2P PSE Money Movement with `subclient_id`

With the Subclient approved, create the R2P PSE Payin by calling Create a Money Movement as you normally would for r2p_pse (see Direct Link for the full rail details), and include the new subclient_id field.

📌

subclient_id is optional by default, but mandatory for agreggators/PSP clients once this requirement is enabled for your account.

If you are an agreggator/PSP, omitting subclient_id — or sending an invalid one or one that doesn't exist — causes the Money Movement request to fail with error MM034. No Money Movement is created in that case.

If your client is not a PSP, subclient_id remains fully optional on r2p_pse Money Movements.

Core Concepts and Terminology

Subclient: A merchant identity record created via POST /subclients or Subclients module in the portal. Must be approved before its id can be used as subclient_id on a Money Movement.

subclient_id: A new root-level field on POST /money_movements. For r2p_pse Payins in Colombia, it links the Money Movement to a previously approved Subclient. Mandatory for agreggators/PSP clients once enabled.

Agreggators/PSP (Payment Service Provider): A client who uses Cobre's services to offer them to their own clients.

Things to Keep in Mind

A Subclient must be approved before its id can be used as subclient_id.

A rejected Subclient cannot be resubmitted — create a new one.

Once approved, a Subclient can be reused across multiple R2P PSE Money Movements.

Today this requirement only applies to r2p_pse Payins in Colombia.

Frequently Asked Questions

Do I need to create a new Subclient for every R2P PSE Money Movement?
No. Once approved, a Subclient can be reused across as many R2P PSE Money Movements as needed.

What happens if I omit subclient_id and I'm a PSP/aggregator?
The Money Movement request fails with error MM034 and no Money Movement is created.

Is this flow available through the Portal?
Subclient creation is available but Money Movement creation for this flow is currently API-only.

Is subclient_id required for other R2P rails (Nequi, Bancolombia, Bre-B) or for Payouts?
No. Today this applies only to r2p_pse Payins in Colombia.

Subclient Management - Payins Colombia

How It Works#

Prerequisites#

Step-by-Step Guide#

Step 1 – Open the Subclients module#

Step 2 – Register a new Subclient#

2.1 Company#

2.2 Representatives#

2.3 Beneficiaries (UBOs)#

2.4 Summary#

Step 3 – Wait for Subclient screening#

Step 4 – Create the R2P PSE Money Movement with subclient_id#

Core Concepts and Terminology#

Things to Keep in Mind#

Frequently Asked Questions#

How It Works

Prerequisites

Step-by-Step Guide

Step 1 – Open the Subclients module

Step 2 – Register a new Subclient

2.1 Company

2.2 Representatives

2.3 Beneficiaries (UBOs)

2.4 Summary

Step 3 – Wait for Subclient screening

Step 4 – Create the R2P PSE Money Movement with `subclient_id`

Core Concepts and Terminology

Things to Keep in Mind

Frequently Asked Questions